yard 0.6.4 → 0.6.5

data/docs/Tags.md

@@ -99,9 +99,13 @@ YARD supplies the following built-in tags:
         
   * `@api`: Declares the API that the object belongs to. Does not display in
     output, but useful for performing queries (`yardoc --query`). Any text is
-    allowable in this tag, and there are no predefined values.
+    allowable in this tag, and there are no predefined values(*).
     
         @api freeform text
+        
+    (*) Note that the special name `@api private` does display a notice in 
+    documentation if it is listed, letting users know that the method is not
+    to be used.
       
   * `@attr`: Declares an attribute from the docstring of a class. Meant to be
     used on Struct classes only (classes that inherit Struct).

data/docs/WhatsNew.md

@@ -19,6 +19,8 @@ What's New in 0.6.x?
 16. **Added `yard config` command to view/edit configuration** (0.6.2)
 17. **Added `yard server -t` template path switch** (0.6.2)
 18. **Added `YARD::Server.register_static_path` for static server assets** (0.6.2)
+19. **YARD::Registry is now thread local** (0.6.5)
+20. **Support for ripper gem in Ruby 1.8.7** (0.6.5)
 
 ## Local documentation server for RubyGems or projects (`yard server`) (0.6.0)
 
@@ -201,7 +203,7 @@ in the templates, use the `--hide-tag` option to hide it from generated output:
 
 ## Added `--transitive-tags` to register transitive tags (0.6.0)
 
-Transitive tags are tags that apply to all descendents of a namespace (class 
+Transitive tags are tags that apply to all descendants of a namespace (class 
 or module) when documented on that namespace. For instance, the `@since` tag 
 is a transitive tag. Applying `@since` to a class will automatically apply 
 `@since` to all methods in the class. Creating a `@since` tag directly on a 
@@ -275,6 +277,21 @@ The server now supports a command to register static asset paths. If you are
 extending the YARD::Server modules, make sure to register your asset paths
 through this method.
 
+## YARD::Registry is now thread local (0.6.5)
+
+Creating a new thread will now implicitly load a new Registry that can be used
+to parse and process new code objects independently of the other threads. Note
+that this means you can no longer use the Registry across threads; you must
+either access the threadlocal object directly, or synchronize threads to do
+the processing in the initial registry's thread.
+
+## Support for ripper gem in Ruby 1.8.7 (0.6.5)
+
+YARD now supports the Ruby 1.8.7 port of the `ripper` gem to improve parsing
+of source, both in terms of performance and functionality. When the `ripper`
+gem is available, YARD will use the "new-style" handlers. You can take advantage
+of this functionality by performing a `gem install ripper`.
+
 
 What's New in 0.5.x?
 ====================

data/lib/rubygems_plugin.rb

@@ -1,100 +1,4 @@
-require 'rubygems/specification'
-require 'rubygems/doc_manager'
-
-unless defined? Gem::DocManager.load_yardoc
-  class Gem::Specification
-    # has_rdoc should not be ignored!
-    overwrite_accessor(:has_rdoc) { @has_rdoc }
-    overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
-  
-    # @since 0.5.3
-    def has_yardoc=(value)
-      @has_rdoc = 'yard'
-    end
-  
-    def has_yardoc
-      @has_rdoc == 'yard'
-    end
-  
-    undef has_rdoc?
-    def has_rdoc?
-      @has_rdoc && @has_rdoc != 'yard'
-    end
-  
-    alias has_yardoc? has_yardoc
-  end
-
-  class Gem::DocManager
-    def self.load_yardoc
-      require File.dirname(__FILE__) + '/yard'
-    end
-  
-    def run_yardoc(*args)
-      args << '--quiet'
-      args << @spec.require_paths
-      if @spec.extra_rdoc_files.size > 0
-        args << '-'
-        args += @spec.extra_rdoc_files
-      end
-      args = args.flatten.map {|arg| arg.to_s }
-
-      old_pwd = Dir.pwd
-      Dir.chdir(@spec.full_gem_path)
-      YARD::CLI::Yardoc.run(*args)
-    rescue Errno::EACCES => e
-      dirname = File.dirname e.message.split("-")[1].strip
-      raise Gem::FilePermissionError.new(dirname)
-    rescue => ex
-      alert_error "While generating documentation for #{@spec.full_name}"
-      ui.errs.puts "... MESSAGE:   #{ex}"
-      ui.errs.puts "... YARDDOC args: #{args.join(' ')}"
-      ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
-      ui.errs.puts "(continuing with the rest of the installation)"
-    ensure
-      Dir.chdir(old_pwd)
-    end
-
-    undef setup_rdoc
-    def setup_rdoc
-      if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
-        raise Gem::FilePermissionError.new(@doc_dir)
-      end
-
-      FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
-
-      self.class.load_rdoc if @spec.has_rdoc?
-      self.class.load_yardoc if @spec.has_yardoc?
-    end
-
-    def install_yardoc
-      rdoc_dir = File.join(@doc_dir, 'rdoc')
-
-      FileUtils.rm_rf rdoc_dir
-
-      say "Installing YARD documentation for #{@spec.full_name}..."
-      run_yardoc '-o', rdoc_dir
-    end
-
-    def install_ri_yard
-      install_ri_yard_orig if @spec.has_rdoc?
-      return if @spec.has_rdoc? == false
-      return if @spec.has_yardoc?
-      
-      self.class.load_yardoc
-      say "Building YARD (yri) index for #{@spec.full_name}..."
-      run_yardoc '-c', '-n'
-    end
-    alias install_ri_yard_orig install_ri
-    alias install_ri install_ri_yard
-
-    def install_rdoc_yard
-      if @spec.has_rdoc?
-        install_rdoc_yard_orig
-      elsif @spec.has_yardoc?
-        install_yardoc
-      end
-    end
-    alias install_rdoc_yard_orig install_rdoc
-    alias install_rdoc install_rdoc_yard
-  end
+unless defined?(Gem::DocManager.load_yardoc)
+  require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/specification')
+  require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/doc_manager')
 end

data/lib/yard.rb

@@ -1,5 +1,5 @@
 module YARD
-  VERSION = "0.6.4"
+  VERSION = "0.6.5"
   
   # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))

data/lib/yard/autoload.rb

@@ -56,46 +56,48 @@ module YARD
   module Handlers
     module Ruby # All Ruby handlers
       module Legacy # Handlers for old Ruby 1.8 parser
-        autoload :Base,                  __p('handlers/ruby/legacy/base')
+        autoload :Base,                   __p('handlers/ruby/legacy/base')
 
-        autoload :AliasHandler,          __p('handlers/ruby/legacy/alias_handler')
-        autoload :AttributeHandler,      __p('handlers/ruby/legacy/attribute_handler')
-        autoload :ClassHandler,          __p('handlers/ruby/legacy/class_handler')
-        autoload :ClassConditionHandler, __p('handlers/ruby/legacy/class_condition_handler')
-        autoload :ClassVariableHandler,  __p('handlers/ruby/legacy/class_variable_handler')
-        autoload :ConstantHandler,       __p('handlers/ruby/legacy/constant_handler')
-        autoload :ExceptionHandler,      __p('handlers/ruby/legacy/exception_handler')
-        autoload :ExtendHandler,         __p('handlers/ruby/legacy/extend_handler')
-        autoload :MethodHandler,         __p('handlers/ruby/legacy/method_handler')
-        autoload :MixinHandler,          __p('handlers/ruby/legacy/mixin_handler')
-        autoload :ModuleHandler,         __p('handlers/ruby/legacy/module_handler')
-        autoload :ProcessHandler,        __p('handlers/ruby/legacy/process_handler')
-        autoload :VisibilityHandler,     __p('handlers/ruby/legacy/visibility_handler')
-        autoload :YieldHandler,          __p('handlers/ruby/legacy/yield_handler')
+        autoload :AliasHandler,           __p('handlers/ruby/legacy/alias_handler')
+        autoload :AttributeHandler,       __p('handlers/ruby/legacy/attribute_handler')
+        autoload :ClassHandler,           __p('handlers/ruby/legacy/class_handler')
+        autoload :ClassConditionHandler,  __p('handlers/ruby/legacy/class_condition_handler')
+        autoload :ClassVariableHandler,   __p('handlers/ruby/legacy/class_variable_handler')
+        autoload :ConstantHandler,        __p('handlers/ruby/legacy/constant_handler')
+        autoload :ExceptionHandler,       __p('handlers/ruby/legacy/exception_handler')
+        autoload :ExtendHandler,          __p('handlers/ruby/legacy/extend_handler')
+        autoload :MethodHandler,          __p('handlers/ruby/legacy/method_handler')
+        autoload :MixinHandler,           __p('handlers/ruby/legacy/mixin_handler')
+        autoload :ModuleHandler,          __p('handlers/ruby/legacy/module_handler')
+        autoload :PrivateConstantHandler, __p('handlers/ruby/legacy/private_constant_handler')
+        autoload :ProcessHandler,         __p('handlers/ruby/legacy/process_handler')
+        autoload :VisibilityHandler,      __p('handlers/ruby/legacy/visibility_handler')
+        autoload :YieldHandler,           __p('handlers/ruby/legacy/yield_handler')
       end
 
-      autoload :Base,                    __p('handlers/ruby/base')
+      autoload :Base,                     __p('handlers/ruby/base')
 
-      autoload :AliasHandler,            __p('handlers/ruby/alias_handler')
-      autoload :AttributeHandler,        __p('handlers/ruby/attribute_handler')
-      autoload :ClassHandler,            __p('handlers/ruby/class_handler')
-      autoload :ClassConditionHandler,   __p('handlers/ruby/class_condition_handler')
-      autoload :ClassVariableHandler,    __p('handlers/ruby/class_variable_handler')
-      autoload :ConstantHandler,         __p('handlers/ruby/constant_handler')
-      autoload :ExceptionHandler,        __p('handlers/ruby/exception_handler')
-      autoload :ExtendHandler,           __p('handlers/ruby/extend_handler')
-      autoload :MethodHandler,           __p('handlers/ruby/method_handler')
-      autoload :MethodConditionHandler,  __p('handlers/ruby/method_condition_handler')
-      autoload :MixinHandler,            __p('handlers/ruby/mixin_handler')
-      autoload :ModuleHandler,           __p('handlers/ruby/module_handler')
-      autoload :ProcessHandler,          __p('handlers/ruby/process_handler')
-      autoload :StructHandlerMethods,    __p('handlers/ruby/struct_handler_methods')
-      autoload :VisibilityHandler,       __p('handlers/ruby/visibility_handler')
-      autoload :YieldHandler,            __p('handlers/ruby/yield_handler')
+      autoload :AliasHandler,             __p('handlers/ruby/alias_handler')
+      autoload :AttributeHandler,         __p('handlers/ruby/attribute_handler')
+      autoload :ClassHandler,             __p('handlers/ruby/class_handler')
+      autoload :ClassConditionHandler,    __p('handlers/ruby/class_condition_handler')
+      autoload :ClassVariableHandler,     __p('handlers/ruby/class_variable_handler')
+      autoload :ConstantHandler,          __p('handlers/ruby/constant_handler')
+      autoload :ExceptionHandler,         __p('handlers/ruby/exception_handler')
+      autoload :ExtendHandler,            __p('handlers/ruby/extend_handler')
+      autoload :MethodHandler,            __p('handlers/ruby/method_handler')
+      autoload :MethodConditionHandler,   __p('handlers/ruby/method_condition_handler')
+      autoload :MixinHandler,             __p('handlers/ruby/mixin_handler')
+      autoload :ModuleHandler,            __p('handlers/ruby/module_handler')
+      autoload :PrivateConstantHandler,   __p('handlers/ruby/private_constant_handler')
+      autoload :ProcessHandler,           __p('handlers/ruby/process_handler')
+      autoload :StructHandlerMethods,     __p('handlers/ruby/struct_handler_methods')
+      autoload :VisibilityHandler,        __p('handlers/ruby/visibility_handler')
+      autoload :YieldHandler,             __p('handlers/ruby/yield_handler')
     end
 
-    autoload :Base,                      __p('handlers/base')
-    autoload :Processor,                 __p('handlers/processor')
+    autoload :Base,                       __p('handlers/base')
+    autoload :Processor,                  __p('handlers/processor')
   end
 
   # The parser namespace holds all parsing engines used by YARD. 
@@ -196,7 +198,7 @@ module YARD
       autoload :BaseHelper,                 __p('templates/helpers/base_helper')
       autoload :FilterHelper,               __p('templates/helpers/filter_helper')
       autoload :HtmlHelper,                 __p('templates/helpers/html_helper')
-      autoload :HtmlSyntaxHighlightHelper,  __p('templates/helpers/html_syntax_highlight_helper' + (RUBY18 ? '18' : ''))
+      autoload :HtmlSyntaxHighlightHelper,  __p('templates/helpers/html_syntax_highlight_helper')
       autoload :MarkupHelper,               __p('templates/helpers/markup_helper')
       autoload :MethodHelper,               __p('templates/helpers/method_helper')
       autoload :ModuleHelper,               __p('templates/helpers/module_helper')

data/lib/yard/cli/config.rb

@@ -12,11 +12,19 @@ module YARD
       # @return [Boolean] whether to reset the {#key}
       attr_accessor :reset
       
+      # @return [Boolean] whether the value being set should be inside a list
+      attr_accessor :as_list
+      
+      # @return [Boolean] whether to append values to existing key
+      attr_accessor :append
+      
       def initialize
         super
         self.key = nil
         self.values = []
         self.reset = false
+        self.append = false
+        self.as_list = false
       end
       
       def description
@@ -44,7 +52,9 @@ module YARD
           YARD::Config.options[key] = YARD::Config::DEFAULT_CONFIG_OPTIONS[key]
         else
           log.debug "Setting #{key} to #{values.inspect}"
-          YARD::Config.options[key] = encode_values
+          items, current_items = encode_values, YARD::Config.options[key]
+          items = [current_items].flatten + [items].flatten if append
+          YARD::Config.options[key] = items
         end
         YARD::Config.save
       end
@@ -61,7 +71,7 @@ module YARD
       end
       
       def encode_values
-        if values.size == 1
+        if values.size == 1 && !as_list
           encode_value(values.first)
         else
           values.map {|v| encode_value(v) }
@@ -79,6 +89,8 @@ module YARD
       
       def optparse(*args)
         list = false
+        self.as_list = false
+        self.append = false
         opts = OptionParser.new
         opts.banner = "Usage: yard config [options] [item [value ...]]"
         opts.separator ""
@@ -100,6 +112,17 @@ module YARD
         opts.on('-r', '--reset', 'Resets the specific item to default') do
           self.reset = true
         end
+        
+        opts.separator ""
+        opts.separator "Modifying keys:"
+        
+        opts.on('-a', '--append', 'Appends items to existing key values') do
+          self.append = true
+        end
+        opts.on('--as-list', 'Forces the value(s) to be wrapped in an array') do
+          self.as_list = true
+        end
+        
         common_options(opts)
         parse_options(opts, args)
         args = [] if list

data/lib/yard/cli/graph.rb

@@ -79,7 +79,7 @@ module YARD
         opts.separator ""
         opts.separator "Output options:"
 
-        opts.on('--dot [OPTIONS]', 'Send the results direclty to `dot` with optional arguments.') do |dotopts|
+        opts.on('--dot [OPTIONS]', 'Send the results directly to `dot` with optional arguments.') do |dotopts|
           @serializer = Serializers::ProcessSerializer.new('dot ' + dotopts.to_s)
         end
         

data/lib/yard/cli/yardoc.rb

@@ -432,6 +432,10 @@ module YARD
         opts.on('-b', '--db FILE', 'Use a specified .yardoc db to load from or save to. (defaults to .yardoc)') do |yfile|
           YARD::Registry.yardoc_file = yfile
         end
+        
+        opts.on('--[no-]single-db', 'Whether code objects should be stored to single database file (advanced)') do |use_single_db|
+          Registry.single_object_db = use_single_db
+        end
 
         opts.on('-n', '--no-output', 'Only generate .yardoc database, no documentation.') do
           self.generate = false

data/lib/yard/code_objects/base.rb

@@ -152,12 +152,10 @@ module YARD
       # @see #dynamic
       def dynamic?; @dynamic end
       
-      # This attribute exists in order to maintain a consistent interface
-      # with the {MethodObject} class, so that a {Verifier} expression need
-      # not check the object type before accessing visibility.
-      # 
-      # @return [Symbol] always returns public for a base object. 
-      def visibility; :public end
+      # @return [Symbol] the visibility of an object (:public, :private, :protected)
+      attr_accessor :visibility
+      undef visibility=
+      def visibility=(v) @visibility = v.to_sym end
       
       class << self
         # Allocates a new code object
@@ -165,6 +163,10 @@ module YARD
         # @see #initialize
         def new(namespace, name, *args, &block)
           raise ArgumentError, "invalid empty object name" if name.to_s.empty?
+          if namespace.is_a?(ConstantObject)
+            namespace = Proxy.new(namespace.namespace, namespace.value)
+          end
+
           if name.to_s[0,2] == NSEP
             name = name.to_s[2..-1]
             namespace = Registry.root
@@ -212,6 +214,7 @@ module YARD
         @current_file_has_comments = false
         @name = name.to_sym
         @source_type = :ruby
+        @visibility = :public
         @tags = []
         @docstring = Docstring.new('', self)
         @namespace = nil
@@ -353,14 +356,14 @@ module YARD
         @docstring_extra ? value + @docstring_extra : value
       end
 
-      # Attaches a docstring to a code oject by parsing the comments attached to the statement
+      # Attaches a docstring to a code object by parsing the comments attached to the statement
       # and filling the {#tags} and {#docstring} methods with the parsed information.
       #
       # @param [String, Array<String>, Docstring] comments 
       #   the comments attached to the code object to be parsed 
       #   into a docstring and meta tags.
       def docstring=(comments)
-        if comments =~ /^\s*\(see (\S+)\s*\)(?:\s|$)/
+        if comments =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
           path, extra = $1, $'
           @docstring_extra = extra.empty? ? nil : Docstring.new(extra, self)
           @docstring = Proxy.new(namespace, path)
@@ -410,7 +413,12 @@ module YARD
         common = [path, other].join(" ").match(/^(\S*)\S*(?: \1\S*)*$/)[1]
         common = path unless common =~ /(\.|::|#)$/
         common = common.sub(/(\.|::|#)[^:#\.]*?$/, '') if same_parent
-        result = other.sub(/^#{Regexp.quote common}(::|\.|)?/, '')
+        if %w(. :).include?(common[-1,1]) || other[common.size,1] == '#'
+          suffix = ''
+        else
+          suffix = '(::|\.)'
+        end
+        result = other.sub(/^#{Regexp.quote common}#{suffix}/, '')
         result.empty? ? other : result
       end
       

data/lib/yard/code_objects/method_object.rb

@@ -1,11 +1,6 @@
 module YARD::CodeObjects
   # Represents a Ruby method in source
   class MethodObject < Base
-    # The visibility of the method (+:public:+, +:protected+, +:private+)
-    # 
-    # @return [Symbol] the method visibility
-    attr_reader :visibility
-    
     # The scope of the method (+:class+ or +:instance+)
     # 
     # @return [Symbol] the scope
@@ -49,10 +44,6 @@ module YARD::CodeObjects
       @scope = v.to_sym 
       YARD::Registry.register(self) if reregister
     end
-    
-    # Sets the visibility
-    # @param [Symbol] v the new visibility (:public, :private, or :protected)
-    def visibility=(v) @visibility = v.to_sym end
       
     # @return whether or not the method is the #initialize constructor method
     def constructor?

data/lib/yard/code_objects/proxy.rb

@@ -47,6 +47,12 @@ module YARD
         @obj = nil
         @imethod ||= nil
         
+        if @namespace.is_a?(ConstantObject)
+          @origname = nil # forget these for a constant
+          @orignamespace = nil
+          @namespace = Proxy.new(@namespace.namespace, @namespace.value)
+        end
+        
         unless @namespace.is_a?(NamespaceObject) or @namespace.is_a?(Proxy)
           raise ArgumentError, "Invalid namespace object: #{namespace}"
         end