yard 0.6.8 → 0.7.0

data/lib/yard/cli/yri.rb

@@ -7,26 +7,26 @@ module YARD
       # 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: 
-      # 
+      # 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
-        
+
       def initialize
         super
         @cache = {}
@@ -36,25 +36,25 @@ 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
       #   YRI.new.run('String#reverse')
       # @param [Array<String>] args each tokenized argument
       def run(*args)
         optparse(*args)
-        
+
         if ::Config::CONFIG['host_os'] =~ /mingw|win32/
           @serializer ||= YARD::Serializers::StdoutSerializer.new
         else
           @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
         end
-        
+
         if @name.nil? || @name.strip.empty?
           print_usage
           exit(1)
@@ -65,9 +65,9 @@ module YARD
           exit(1)
         end
       end
-      
+
       protected
-      
+
       # Prints the command usage
       # @return [void]
       # @since 0.5.6
@@ -75,41 +75,41 @@ module YARD
         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
-        
+
         File.open!(CACHE_FILE, 'w') do |file|
           @cache.each do |key, value|
             file.puts("#{key} #{value}")
           end
         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 ? "#" : "") + 
-            object.namespace.aliases[object].to_s) 
+          tmp = P(object.namespace, (object.scope == :instance ? "#" : "") +
+            object.namespace.aliases[object].to_s)
           object = tmp unless YARD::CodeObjects::Proxy === tmp
         end
         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)
-        
+
         log.debug "Searching for #{name} in search paths"
         @search_paths.each do |path|
           next unless File.exist?(path)
@@ -123,9 +123,9 @@ module YARD
         end
         nil
       end
-      
+
       private
-      
+
       # Loads {CACHE_FILE}
       # @return [void]
       def load_cache
@@ -135,7 +135,7 @@ module YARD
           @cache[line[0]] = line[1]
         end
       end
-      
+
       # Adds all RubyGems yardoc files to search paths
       # @return [void]
       def add_gem_paths
@@ -153,7 +153,7 @@ module YARD
         @search_paths += gem_paths
       rescue LoadError
       end
-      
+
       # Adds paths in {SEARCH_PATHS_FILE}
       # @since 0.5.1
       def add_default_paths
@@ -162,7 +162,7 @@ module YARD
         paths = File.readlines(SEARCH_PATHS_FILE).map {|l| l.strip }
         @search_paths.push(*paths)
       end
-      
+
       # Parses commandline options.
       # @param [Array<String>] args each tokenized argument
       def optparse(*args)
@@ -179,11 +179,11 @@ module YARD
         opts.on('-T', '--no-pager', 'No pager') do
           @serializer = YARD::Serializers::StdoutSerializer.new
         end
-        
+
         opts.on('-p PAGER', '--pager') do |pager|
           @serializer = YARD::Serializers::ProcessSerializer.new(pager)
         end
-        
+
         common_options(opts)
         parse_options(opts, args)
         @name = args.first

data/lib/yard/code_objects/base.rb

@@ -4,15 +4,15 @@ module YARD
     # but also disallows any {Proxy} objects from being added.
     class CodeObjectList < Array
       # Creates a new object list associated with a namespace
-      # 
+      #
       # @param [NamespaceObject] owner the namespace the list should be associated with
       # @return [CodeObjectList]
       def initialize(owner = Registry.root)
         @owner = owner
       end
-      
+
       # Adds a new value to the list
-      # 
+      #
       # @param [Base] value a code object to add
       # @return [CodeObjectList] self
       def push(value)
@@ -26,140 +26,140 @@ module YARD
       end
       alias_method :<<, :push
     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*[!?=]?|[-+~]\@|<<|>>|=~|===?|<=>|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
-    
+
     # 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", 
+    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"]
     # 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", 
+    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", 
+    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
-    # object is any entity in the Ruby language (class, method, module). A 
+    # object is any entity in the Ruby language (class, method, module). A
     # DSL might subclass +Base+ to create a new custom object representing
-    # a new entity type. 
-    # 
+    # a new entity type.
+    #
     # == Registry Integration
-    # Any created object associated with a namespace is immediately registered 
+    # Any created object associated with a namespace is immediately registered
     # with the registry. This allows the Registry to act as an identity map
     # to ensure that no object is represented by more than one Ruby object
     # in memory. A unique {#path} is essential for this identity map to work
     # correctly.
-    # 
+    #
     # == Custom Attributes
     # Code objects allow arbitrary custom attributes to be set using the
     # {#[]=} assignment method.
-    # 
+    #
     # == Namespaces
     # There is a special type of object called a "namespace". These are subclasses
     # of the {NamespaceObject} and represent Ruby entities that can have
     # objects defined within them. Classically these are modules and classes,
-    # though a DSL might create a custom {NamespaceObject} to describe a 
+    # though a DSL might create a custom {NamespaceObject} to describe a
     # specific set of objects.
-    # 
+    #
     # @abstract This class should not be used directly. Instead, create a
     #   subclass that implements {#path}, {#sep} or {#type}.
     # @see Registry
     # @see #path
     # @see #[]=
     # @see NamespaceObject
-    class Base  
+    class Base
       # The files the object was defined in. To add a file, use {#add_file}.
       # @return [Array<String>] a list of files
       # @see #add_file
       attr_reader :files
-      
+
       # The namespace the object is defined in. If the object is in the
       # top level namespace, this is {Registry.root}
       # @return [NamespaceObject] the namespace object
       attr_reader :namespace
-      
+
       # The source code associated with the object
       # @return [String, nil] source, if present, or nil
       attr_reader :source
-      
+
       # Language of the source code associated with the object. Defaults to
       # +:ruby+.
-      # 
+      #
       # @return [Symbol] the language type
       attr_accessor :source_type
-      
+
       # The one line signature representing an object. For a method, this will
       # be of the form "def meth(arguments...)". This is usually the first
       # source line.
-      # 
+      #
       # @return [String] a line of source
       attr_accessor :signature
-      
+
       # The documentation string associated with the object
       # @return [Docstring] the documentation string
       attr_reader :docstring
-      
+
       # Marks whether or not the method is conditionally defined at runtime
       # @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
-      
+
       # @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
-        # @return [Base] 
+        # @return [Base]
         # @see #initialize
         def new(namespace, name, *args, &block)
           raise ArgumentError, "invalid empty object name" if name.to_s.empty?
@@ -170,28 +170,28 @@ module YARD
           if name.to_s[0,2] == NSEP
             name = name.to_s[2..-1]
             namespace = Registry.root
-          elsif name =~ /(?:#{NSEPQ}|#{ISEPQ}|#{CSEPQ})([^#{NSEPQ}#{ISEPQ}#{CSEPQ}]+)$/
+          elsif name =~ /(?:#{NSEPQ})([^:]+)$/
             return new(Proxy.new(namespace, $`), $1, *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
-        # 
+        #
         # @param [Object] other the other object to compare classes with
         # @return [Boolean] true if other is a subclass of self
         def ===(other)
           other.is_a?(self)
         end
       end
-          
+
       # Creates a new code object
-      # 
+      #
       # @example Create a method in the root namespace
       #   CodeObjects::Base.new(:root, '#method') # => #<yardoc method #method>
       # @example Create class Z inside namespace X::Y
@@ -200,12 +200,12 @@ module YARD
       # @param [NamespaceObject] namespace the namespace the object belongs in,
       #   {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. 
+      # @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, &block)
-        if namespace && namespace != :root && 
+        if namespace && namespace != :root &&
             !namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
           raise ArgumentError, "Invalid namespace object: #{namespace}"
         end
@@ -221,20 +221,20 @@ module YARD
         self.namespace = namespace
         yield(self) if block_given?
       end
-      
+
       # The name of the object
       # @param [Boolean] prefix whether to show a prefix. Implement
       #   this in a subclass to define how the prefix is showed.
       # @return [Symbol] if prefix is false, the symbolized name
-      # @return [String] if prefix is true, prefix + the name as a String. 
+      # @return [String] if prefix is true, prefix + the name as a String.
       #   This must be implemented by the subclass.
       def name(prefix = false)
         prefix ? @name.to_s : @name
       end
-      
+
       # Associates a file with a code object, optionally adding the line where it was defined.
       # By convention, '<stdin>' should be used to associate code that comes form standard input.
-      # 
+      #
       # @param [String] file the filename ('<stdin>' for standard input)
       # @param [Fixnum, nil] line the line number where the object lies in the file
       # @param [Boolean] has_comments whether or not the definition has comments associated. This
@@ -246,28 +246,28 @@ module YARD
         return if files.include?(obj)
         if has_comments && !@current_file_has_comments
           @current_file_has_comments = true
-          @files.unshift(obj) 
+          @files.unshift(obj)
         else
           @files << obj # back of the line
         end
       end
-      
+
       # Returns the filename the object was first parsed at, taking
       # definitions with docstrings first.
-      # 
+      #
       # @return [String] a filename
       def file
         @files.first ? @files.first[0] : nil
       end
 
       # Returns the line the object was first parsed at (or nil)
-      # 
+      #
       # @return [Fixnum] the line where the object was first defined.
       # @return [nil] if there is no line associated with the object
       def line
         @files.first ? @files.first[1] : nil
       end
-      
+
       # Tests if another object is equal to this, including a proxy
       # @param [Base, Proxy] other if other is a {Proxy}, tests if
       #   the paths are equal
@@ -281,7 +281,7 @@ module YARD
       end
       alias == equal?
       alias eql? equal?
-      
+
       # @return [Integer] the object's hash value (for equality checking)
       def hash; path.hash end
 
@@ -296,11 +296,11 @@ module YARD
           instance_variable_get("@#{key}")
         end
       end
-      
+
       # Sets a custom attribute on the object
       # @param [#to_s] key the name of the custom attribute
       # @param [Object] value the value to associate
-      # @return [void] 
+      # @return [void]
       # @see #[]
       def []=(key, value)
         if respond_to?("#{key}=")
@@ -309,7 +309,7 @@ module YARD
           instance_variable_set("@#{key}", value)
         end
       end
-      
+
       # @overload dynamic_attr_name
       #   @return the value of attribute named by the method attribute name
       #   @raise [NoMethodError] if no method or custom attribute exists by
@@ -331,8 +331,8 @@ module YARD
 
       # Attaches source code to a code object with an optional file location
       #
-      # @param [#source, String] statement 
-      #   the +Parser::Statement+ holding the source code or the raw source 
+      # @param [#source, String] statement
+      #   the +Parser::Statement+ holding the source code or the raw source
       #   as a +String+ for the definition of the code object only (not the block)
       def source=(statement)
         if statement.respond_to?(:source)
@@ -343,49 +343,49 @@ module YARD
           @source = format_source(statement.to_s)
         end
       end
-      
+
       def docstring
-        value = case @docstring
+        return @docstring if !@docstring_extra
+        case @docstring
         when Proxy
-          Docstring.new("", self)
+          return @docstring_extra
         when Base
-          @docstring.docstring
-        else
-          @docstring
+          @docstring = @docstring.docstring + @docstring_extra
+          @docstring_extra = nil
         end
-        @docstring_extra ? value + @docstring_extra : value
+        @docstring
       end
 
       # 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 
+      # @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 =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
           path, extra = $1, $'
-          @docstring_extra = extra.empty? ? nil : Docstring.new(extra, self)
+          @docstring_extra = 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.
       # Override this method to provide a custom object type
-      # 
+      #
       # @return [Symbol] the type of code object this represents
       def type
         self.class.name.split(/#{NSEPQ}/).last.gsub(/Object$/, '').downcase.to_sym
       end
-    
+
       # Represents the unique path of the object. The default implementation
       # joins the path of {#namespace} with {#name} via the value of {#sep}.
-      # Custom code objects should ensure that the path is unique to the code 
+      # Custom code objects should ensure that the path is unique to the code
       # object by either overriding {#sep} or this method.
-      # 
+      #
       # @example The path of an instance method
       #   MethodObject.new(P("A::B"), :c).path # => "A::B#c"
       # @return [String] the unique path of the object
@@ -398,7 +398,7 @@ module YARD
         end
       end
       alias_method :to_s, :path
-      
+
       # @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
@@ -421,9 +421,9 @@ module YARD
         result = other.sub(/^#{Regexp.quote common}#{suffix}/, '')
         result.empty? ? other : result
       end
-      
+
       # Renders the object using the {Templates::Engine templating system}.
-      # 
+      #
       # @example Formats a class in plaintext
       #   puts P('MyClass').format
       # @example Formats a method in html with rdoc markup
@@ -439,26 +439,26 @@ module YARD
         options.merge!(:object => self)
         Templates::Engine.render(options)
       end
-      
+
       # Inspects the object, returning the type and path
       # @return [String] a string describing the object
       def inspect
         "#<yardoc #{type} #{path}>"
       end
-    
+
       # Sets the namespace the object is defined in.
-      # 
-      # @param [NamespaceObject, :root, nil] obj the new namespace (:root 
+      #
+      # @param [NamespaceObject, :root, nil] obj the new namespace (:root
       #   for {Registry.root}). If obj is nil, the object is unregistered
       #   from the Registry.
       def namespace=(obj)
         if @namespace
-          @namespace.children.delete(self) 
+          @namespace.children.delete(self)
           Registry.delete(self)
         end
-        
+
         @namespace = (obj == :root ? Registry.root : obj)
-      
+
         if @namespace
           reg_obj = Registry.at(path)
           return if reg_obj && reg_obj.class == self.class
@@ -466,38 +466,38 @@ module YARD
           Registry.register(self)
         end
       end
-    
+
       alias_method :parent, :namespace
       alias_method :parent=, :namespace=
 
       # Gets a tag from the {#docstring}
       # @see Docstring#tag
       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
-      
+
       # Tests if the {#docstring} has a tag
       # @see Docstring#has_tag?
       def has_tag?(name); docstring.has_tag?(name) end
-      
+
       # @return whether or not this object is a RootObject
       def root?; false end
 
       protected
-    
+
       # Override this method with a custom component separator. For instance,
       # {MethodObject} implements sep as '#' or '.' (depending on if the
       # method is instance or class respectively). {#path} depends on this
       # value to generate the full path in the form: namespace.path + sep + name
-      # 
+      #
       # @return [String] the component that separates the namespace path
       #   and the name (default is {NSEP})
       def sep; NSEP end
 
       # Formats source code by removing leading indentation
-      # 
+      #
       # @param [String] source the source code to format
       # @return [String] formatted source
       def format_source(source)