yard 0.5.8 → 0.6.0

data/lib/yard/cli/yri.rb

@@ -3,10 +3,26 @@ require 'rbconfig'
 module YARD
   module CLI
     # A tool to view documentation in the console like `ri`
-    class YRI < Base
+    class YRI < Command
+      # The location in {YARD::CONFIG_DIR} where the YRI cache file is loaded
+      # from.
       CACHE_FILE = File.expand_path('~/.yard/yri_cache')
+      
+      # A file containing all paths, delimited by newlines, to search for
+      # yardoc databases.
+      # @since 0.5.1
       SEARCH_PATHS_FILE = File.expand_path('~/.yard/yri_search_paths')
       
+      # Default search paths that should be loaded dynamically into YRI. These paths
+      # take precedence over all other paths ({SEARCH_PATHS_FILE} and RubyGems
+      # paths). To add a path, call: 
+      # 
+      #   DEFAULT_SEARCH_PATHS.push("/path/to/.yardoc")
+      # 
+      # @return [Array<String>] a list of extra search paths
+      # @since 0.6.0
+      DEFAULT_SEARCH_PATHS = []
+      
       # Helper method to run the utility on an instance.
       # @see #run
       def self.run(*args) new.run(*args) end
@@ -20,7 +36,11 @@ module YARD
         load_cache
         @search_paths.uniq!
       end
-        
+      
+      def description
+        "A tool to view documentation in the console like `ri`"
+      end
+      
       # Runs the command-line utility.
       # 
       # @example
@@ -48,11 +68,16 @@ module YARD
       
       protected
       
+      # Prints the command usage
+      # @return [void]
+      # @since 0.5.6
       def print_usage
         puts "Usage: yri [options] <Path to object>"
         puts "See yri --help for more options."
       end
       
+      # Caches the .yardoc file where an object can be found in the {CACHE_FILE}
+      # @return [void]
       def cache_object(name, path)
         return if path == Registry.yardoc_file
         @cache[name] = path
@@ -64,6 +89,8 @@ module YARD
         end
       end
       
+      # @param [CodeObjects::Base] object the object to print.
+      # @return [String] the formatted output for an object.
       def print_object(object)
         if object.type == :method && object.is_alias?
           tmp = P(object.namespace, (object.scope == :instance ? "#" : "") + 
@@ -73,6 +100,12 @@ module YARD
         object.format(:serializer => @serializer)
       end
       
+      # Locates an object by name starting in the cached paths and then
+      # searching through any search paths.
+      # 
+      # @param [String] name the full name of the object
+      # @return [CodeObjects::Base] an object if found
+      # @return [nil] if no object is found
       def find_object(name)
         @search_paths.unshift(@cache[name]) if @cache[name]
         @search_paths.unshift(Registry.yardoc_file)
@@ -93,6 +126,8 @@ module YARD
       
       private
       
+      # Loads {CACHE_FILE}
+      # @return [void]
       def load_cache
         return unless File.file?(CACHE_FILE)
         File.readlines(CACHE_FILE).each do |line|
@@ -101,22 +136,28 @@ module YARD
         end
       end
       
+      # Adds all RubyGems yardoc files to search paths
+      # @return [void]
       def add_gem_paths
         require 'rubygems'
+        gem_paths = []
         Gem.source_index.find_name('').each do |spec|
           if yfile = Registry.yardoc_file_for_gem(spec.name)
             if spec.name =~ /^yard-doc-/
-              @search_paths.unshift(yfile)
+              gem_paths.unshift(yfile)
             else
-              @search_paths.push(yfile)
+              gem_paths.push(yfile)
             end
           end
         end
+        @search_paths += gem_paths
       rescue LoadError
       end
       
       # Adds paths in {SEARCH_PATHS_FILE}
+      # @since 0.5.1
       def add_default_paths
+        @search_paths.push(*DEFAULT_SEARCH_PATHS)
         return unless File.file?(SEARCH_PATHS_FILE)
         paths = File.readlines(SEARCH_PATHS_FILE).map {|l| l.strip }
         @search_paths.push(*paths)

data/lib/yard/code_objects/base.rb

@@ -28,31 +28,55 @@ module YARD
     end
     
     
+    # Namespace separator
     NSEP = '::'
+    
+    # Regex-quoted namespace separator
     NSEPQ = NSEP
+    
+    # Instance method separator
     ISEP = '#'
+
+    # Regex-quoted instance method separator
     ISEPQ = ISEP
+    
+    # Class method separator
     CSEP = '.'
+    
+    # Regex-quoted class method separator
     CSEPQ = Regexp.quote CSEP
+    
+    # Regular expression to match constant name
     CONSTANTMATCH = /[A-Z]\w*/
+    
+    # Regular expression to match namespaces (const A or complex path A::B)
     NAMESPACEMATCH = /(?:(?:#{NSEPQ})?#{CONSTANTMATCH})+/
+    
+    # Regular expression to match a method name
     METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|<=>|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
-    METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|self)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/
     
+    # Regular expression to match a fully qualified method def (self.foo, Class.foo).
+    METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|[a-z]\w*)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/
+    
+    # All builtin Ruby exception classes for inheritance tree.
     BUILTIN_EXCEPTIONS = ["SecurityError", "Exception", "NoMethodError", "FloatDomainError", 
       "IOError", "TypeError", "NotImplementedError", "SystemExit", "Interrupt", "SyntaxError", 
       "RangeError", "NoMemoryError", "ArgumentError", "ThreadError", "EOFError", "RuntimeError", 
       "ZeroDivisionError", "StandardError", "LoadError", "NameError", "LocalJumpError", "SystemCallError", 
       "SignalException", "ScriptError", "SystemStackError", "RegexpError", "IndexError"]
-    # Note: MatchingData is a 1.8.x legacy class
+    # All builtin Ruby classes for inheritance tree.
+    # @note MatchingData is a 1.8.x legacy class
     BUILTIN_CLASSES = ["TrueClass", "Array", "Dir", "Struct", "UnboundMethod", "Object", "Fixnum", "Float", 
       "ThreadGroup", "MatchingData", "MatchData", "Proc", "Binding", "Class", "Time", "Bignum", "NilClass", "Symbol", 
       "Numeric", "String", "Data", "MatchData", "Regexp", "Integer", "File", "IO", "Range", "FalseClass", 
       "Method", "Continuation", "Thread", "Hash", "Module"] + BUILTIN_EXCEPTIONS
+    # All builtin Ruby modules for mixin handling.
     BUILTIN_MODULES = ["ObjectSpace", "Signal", "Marshal", "Kernel", "Process", "GC", "FileTest", "Enumerable", 
       "Comparable", "Errno", "Precision", "Math"]
+    # All builtin Ruby classes and modules.
     BUILTIN_ALL = BUILTIN_CLASSES + BUILTIN_MODULES
     
+    # Hash of {BUILTIN_EXCEPTIONS} as keys and true as value (for O(1) lookups)
     BUILTIN_EXCEPTIONS_HASH = BUILTIN_EXCEPTIONS.inject({}) {|h,n| h.update(n => true) }
     
     # +Base+ is the superclass of all code objects recognized by YARD. A code
@@ -91,7 +115,7 @@ module YARD
       attr_reader :files
       
       # The namespace the object is defined in. If the object is in the
-      # top level namespace, this is {Registry#root}
+      # top level namespace, this is {Registry.root}
       # @return [NamespaceObject] the namespace object
       attr_reader :namespace
       
@@ -120,10 +144,21 @@ module YARD
       # @return [Boolean] true if the method is conditionally defined at runtime
       attr_accessor :dynamic
       
+      # @return [String] the group this object is associated with
+      # @since 0.6.0
+      attr_accessor :group
+      
       # Is the object defined conditionally at runtime?
       # @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
+      
       class << self
         # Allocates a new code object
         # @return [Base] 
@@ -137,26 +172,11 @@ module YARD
             return new(Proxy.new(namespace, $`), $1, *args, &block)
           end
           
-          keyname = namespace && namespace.respond_to?(:path) ? namespace.path : ''
-          if self == RootObject
-            keyname = :root
-          elsif self == MethodObject
-            keyname += (args.first && args.first.to_sym == :class ? CSEP : ISEP) + name.to_s
-          elsif keyname.empty?
-            keyname = name.to_s
-          else
-            keyname += NSEP + name.to_s
-          end
-          
-          obj = Registry.objects[keyname]
-          obj = nil if obj && obj.class != self
-          
-          if self != RootObject && obj
-            yield(obj) if block_given?
-            obj
-          else
-            Registry.objects[keyname] = super(namespace, name, *args, &block)
-          end
+          obj = super(namespace, name, *args)
+          existing_obj = Registry.at(obj.path)
+          obj = existing_obj if existing_obj && existing_obj.class == self
+          yield(obj) if block_given?
+          obj
         end
         
         # Compares the class with subclasses
@@ -176,13 +196,13 @@ module YARD
       #   CodeObjects::Base.new(P("X::Y"), :Z) # or
       #   CodeObjects::Base.new(Registry.root, "X::Y")
       # @param [NamespaceObject] namespace the namespace the object belongs in,
-      #   {Registry#root} or :root should be provided if it is associated with
+      #   {Registry.root} or :root should be provided if it is associated with
       #   the top level namespace.
       # @param [Symbol, String] name the name (or complex path) of the object. 
       # @yield [self] a block to perform any extra initialization on the object
       # @yieldparam [Base] self the newly initialized code object
       # @return [Base] the newly created object
-      def initialize(namespace, name, *args)
+      def initialize(namespace, name, *args, &block)
         if namespace && namespace != :root && 
             !namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
           raise ArgumentError, "Invalid namespace object: #{namespace}"
@@ -220,6 +240,7 @@ module YARD
       def add_file(file, line = nil, has_comments = false)
         raise(ArgumentError, "file cannot be nil or empty") if file.nil? || file == ''
         obj = [file.to_s, line]
+        return if files.include?(obj)
         if has_comments && !@current_file_has_comments
           @current_file_has_comments = true
           @files.unshift(obj) 
@@ -319,6 +340,18 @@ module YARD
           @source = format_source(statement.to_s)
         end
       end
+      
+      def docstring
+        value = case @docstring
+        when Proxy
+          Docstring.new("", self)
+        when Base
+          @docstring.docstring
+        else
+          @docstring
+        end
+        @docstring_extra ? value + @docstring_extra : value
+      end
 
       # Attaches a docstring to a code oject by parsing the comments attached to the statement
       # and filling the {#tags} and {#docstring} methods with the parsed information.
@@ -327,7 +360,14 @@ module YARD
       #   the comments attached to the code object to be parsed 
       #   into a docstring and meta tags.
       def docstring=(comments)
-        @docstring = Docstring === comments ? comments : Docstring.new(comments, self)
+        if comments =~ /^\s*\(see (\S+)\s*\)(?:\s|$)/
+          path, extra = $1, $'
+          @docstring_extra = extra.empty? ? nil : Docstring.new(extra, self)
+          @docstring = Proxy.new(namespace, path)
+        else
+          @docstring_extra = nil
+          @docstring = Docstring === comments ? comments : Docstring.new(comments, self)
+        end
       end
       
       # Default type is the lowercase class name without the "Object" suffix.
@@ -358,6 +398,7 @@ module YARD
       
       # @param [Base, String] other another code object (or object path)
       # @return [String] the shortest relative path from this object to +other+
+      # @since 0.5.3
       def relative_path(other)
         other = other.path if other.respond_to?(:path)
         return other unless namespace
@@ -391,7 +432,7 @@ module YARD
       # Sets the namespace the object is defined in.
       # 
       # @param [NamespaceObject, :root, nil] obj the new namespace (:root 
-      #   for {Registry#root}). If obj is nil, the object is unregistered
+      #   for {Registry.root}). If obj is nil, the object is unregistered
       #   from the Registry.
       def namespace=(obj)
         if @namespace
@@ -402,6 +443,8 @@ module YARD
         @namespace = (obj == :root ? Registry.root : obj)
       
         if @namespace
+          reg_obj = Registry.at(path)
+          return if reg_obj && reg_obj.class == self.class
           @namespace.children << self unless @namespace.is_a?(Proxy)
           Registry.register(self)
         end
@@ -412,15 +455,15 @@ module YARD
 
       # Gets a tag from the {#docstring}
       # @see Docstring#tag
-      def tag(name); @docstring.tag(name) end
+      def tag(name); docstring.tag(name) end
       
       # Gets a list of tags from the {#docstring}
       # @see Docstring#tags
-      def tags(name = nil); @docstring.tags(name) end
+      def tags(name = nil); docstring.tags(name) end
       
       # Tests if the {#docstring} has a tag
       # @see Docstring#has_tag?
-      def has_tag?(name); @docstring.has_tag?(name) end
+      def has_tag?(name); docstring.has_tag?(name) end
       
       # @return whether or not this object is a RootObject
       def root?; false end

data/lib/yard/code_objects/class_object.rb

@@ -1,4 +1,6 @@
 module YARD::CodeObjects
+  # A ClassObject represents a Ruby class in source code. It is a {ModuleObject}
+  # with extra inheritance semantics through the superclass.
   class ClassObject < NamespaceObject
     # The {ClassObject} that this class object inherits from in Ruby source.
     # @return [ClassObject] a class object that is the superclass of this one
@@ -59,7 +61,12 @@ module YARD::CodeObjects
     # @return [Array<MethodObject>] the list of methods that matched
     def meths(opts = {})
       opts = SymbolHash[:inherited => true].update(opts)
-      super(opts) + (opts[:inherited] ? inherited_meths(opts) : [])
+      list = super(opts) 
+      list += inherited_meths(opts).reject do |o|
+        next(false) if opts[:all]
+        list.find {|o2| o2.name == o.name && o2.scope == o.scope }
+      end if opts[:inherited]
+      list
     end
     
     # Returns only the methods that were inherited.
@@ -71,6 +78,7 @@ module YARD::CodeObjects
           list
         else
           list += superclass.meths(opts).reject do |o|
+            next(false) if opts[:all]
             child(:name => o.name, :scope => o.scope) ||
               list.find {|o2| o2.name == o.name && o2.scope == o.scope }
           end

data/lib/yard/code_objects/method_object.rb

@@ -61,17 +61,20 @@ module YARD::CodeObjects
     # Returns the read/writer info for the attribute if it is one
     # @return [SymbolHash] if there is information about the attribute
     # @return [nil] if the method is not an attribute
+    # @since 0.5.3
     def attr_info
       return nil unless namespace.is_a?(NamespaceObject)
       namespace.attributes[scope][name.to_s.gsub(/=$/, '')]
     end
     
     # @return [Boolean] whether the method is a writer attribute
+    # @since 0.5.3
     def writer?
       !!((info = attr_info) && info[:write] == self)
     end
 
     # @return [Boolean] whether the method is a reader attribute
+    # @since 0.5.3
     def reader?
       !!((info = attr_info) && info[:read] == self)
     end
@@ -97,6 +100,14 @@ module YARD::CodeObjects
       explicit ? true : false
     end
     
+    # @return [MethodObject] the object that this method overrides
+    # @return [nil] if it does not override a method
+    # @since 0.6.0
+    def overridden_method
+      meths = namespace.meths(:all => true)
+      meths.find {|m| m.path != path && m.name == name && m.scope == scope }
+    end
+    
     # Returns all alias names of the object
     # @return [Array<Symbol>] the alias names
     def aliases

data/lib/yard/code_objects/namespace_object.rb

@@ -6,6 +6,10 @@ module YARD::CodeObjects
     attr_writer :constants, :cvars, :mixins, :child, :meths
     attr_writer :class_attributes, :instance_attributes
     attr_writer :included_constants, :included_meths
+    
+    # @return [Array<String>] a list of ordered group names inside the namespace
+    # @since 0.6.0
+    attr_accessor :groups
 
     # The list of objects defined in this namespace
     # @return [Array<Base>] a list of objects
@@ -55,6 +59,7 @@ module YARD::CodeObjects
       @instance_mixins = CodeObjectList.new(self)
       @attributes = SymbolHash[:class => SymbolHash.new, :instance => SymbolHash.new]
       @aliases = {}
+      @groups = []
       super
     end
     
@@ -139,9 +144,10 @@ module YARD::CodeObjects
     def included_meths(opts = {})
       opts = SymbolHash[:scope => [:instance, :class]].update(opts)
       [opts[:scope]].flatten.map do |scope|
-        mixins(scope).reverse.inject([]) do |list, mixin|
+        mixins(scope).inject([]) do |list, mixin|
           next list if mixin.is_a?(Proxy)
           arr = mixin.meths(opts.merge(:scope => :instance)).reject do |o|
+            next false if opts[:all]
             child(:name => o.name, :scope => scope) || list.find {|o2| o2.name == o.name }
           end
           arr.map! {|o| ExtendedMethodObject.new(o) } if scope == :class
@@ -164,7 +170,7 @@ module YARD::CodeObjects
     # Returns constants included from any mixins
     # @return [Array<ConstantObject>] a list of constant objects
     def included_constants
-      instance_mixins.reverse.inject([]) do |list, mixin|
+      instance_mixins.inject([]) do |list, mixin|
         if mixin.respond_to? :constants
           list += mixin.constants.reject do |o| 
             child(:name => o.name) || list.find {|o2| o2.name == o.name }

data/lib/yard/code_objects/proxy.rb

@@ -6,14 +6,14 @@ module YARD
     # The Proxy class is a way to lazily resolve code objects in
     # cases where the object may not yet exist. A proxy simply stores
     # an unresolved path until a method is called on the object, at which
-    # point it does a lookup using {Registry#resolve}. If the object is
+    # point it does a lookup using {Registry.resolve}. If the object is
     # not found, a warning is raised and {ProxyMethodError} might be raised.
     # 
     # @example Creates a Proxy to the String class from a module
     #   # When the String class is parsed this method will
     #   # begin to act like the String ClassObject.
     #   Proxy.new(mymoduleobj, "String")
-    # @see Registry#resolve
+    # @see Registry.resolve
     # @see ProxyMethodError
     class Proxy
       def self.===(other) other.is_a?(self) end