yard 0.5.8 → 0.6.0

data/lib/yard/core_ext/array.rb

@@ -1,5 +1,5 @@
 class Array
-  # Places a value before or after another object (by value) in
+  # Places values before or after another object (by value) in
   # an array. This is used in tandem with the before and after
   # methods of the {Insertion} class.
   # 
@@ -7,55 +7,9 @@ class Array
   #   [1, 2, 3].place(4).before(3) # => [1, 2, 4, 3]
   # @example Places an item after another
   #   [:a, :b, :c].place(:x).after(:a) # => [:a, :x, :b, :c]
-  # @param [Object] value value to insert
+  # @param [Array] values value to insert
   # @return [Insertion] an insertion object to 
   # @see Insertion#before
   # @see Insertion#after
-  def place(value) Insertion.new(self, value) end
-end
-
-# The Insertion class inserts a value before or after another
-# value in a list.
-# 
-# @example
-#   Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]
-class Insertion
-  # Creates an insertion object on a list with a value to be
-  # inserted. To finalize the insertion, call {#before} or
-  # {#after} on the object.
-  # 
-  # @param [Array] list the list to perform the insertion on
-  # @param [Object] value the value to insert
-  def initialize(list, value) @list, @value = list, value end
-    
-  # Inserts the value before +val+
-  # @param [Object] val the object the value will be inserted before
-  def before(val) insertion(val, 0) end
-    
-  # Inserts the value after +val+. 
-  # 
-  # @example If subsections are ignored
-  #   Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]
-  # @param [Object] val the object the value will be inserted after
-  # @param [Boolean] ignore_subsections treat any Array objects that follow val as
-  #   associated and do not split them up.
-  def after(val, ignore_subsections = true) insertion(val, 1, ignore_subsections) end
-
-  private
-
-  # This method performs the actual insertion
-  # 
-  # @param [Object] val the value to insert
-  # @param [Fixnum] rel the relative index (0 or 1) of where the object
-  #   should be placed
-  # @param [Boolean] ignore_subsections see {#after} for an explanation.
-  def insertion(val, rel, ignore_subsections = true) 
-    if index = @list.index(val)
-      if ignore_subsections && rel == 1 && @list[index + 1].is_a?(Array)
-        rel += 1
-      end
-      @list[index+rel,0] = @value 
-    end
-    @list
-  end
+  def place(*values) Insertion.new(self, values) end
 end

data/lib/yard/core_ext/file.rb

@@ -4,6 +4,8 @@ class File
   RELATIVE_PARENTDIR = '..'
   RELATIVE_SAMEDIR = '.'
   
+  # @group Manipulating Paths
+  
   # Turns a path +to+ into a relative path from starting
   # point +from+. The argument +from+ is assumed to be
   # a filename. To treat it as a directory, make sure it
@@ -43,7 +45,11 @@ class File
     File.join(*path)
   end
   
+  # @group Reading Files
+  
   # Forces opening a file (for writing) by first creating the file's directory
+  # @param [String] file the filename to open
+  # @since 0.5.2
   def self.open!(file, *args, &block)
     dir = dirname(file)
     FileUtils.mkdir_p(dir) unless directory?(dir)
@@ -52,6 +58,7 @@ class File
   
   # Reads a file with binary encoding
   # @return [String] the ascii-8bit encoded data
+  # @since 0.5.3
   def self.read_binary(file)
     File.open(file, 'rb') {|f| f.read }
   end

data/lib/yard/core_ext/insertion.rb

@@ -0,0 +1,60 @@
+# The Insertion class inserts a value before or after another
+# value in a list.
+# 
+# @example
+#   Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]
+class Insertion
+  # Creates an insertion object on a list with a value to be
+  # inserted. To finalize the insertion, call {#before} or
+  # {#after} on the object.
+  # 
+  # @param [Array] list the list to perform the insertion on
+  # @param [Object] value the value to insert
+  def initialize(list, value) @list, @values = list, (Array === value ? value : [value]) end
+    
+  # Inserts the value before +val+
+  # @param [Object] val the object the value will be inserted before
+  # @param [Boolean] recursive look inside sublists
+  def before(val, recursive = false) insertion(val, 0, recursive) end
+    
+  # Inserts the value after +val+. 
+  # 
+  # @example If subsections are ignored
+  #   Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]
+  # @param [Object] val the object the value will be inserted after
+  # @param [Boolean] recursive look inside sublists
+  def after(val, recursive = false) insertion(val, 1, recursive) end
+    
+  # Alias for {#before} with +recursive+ set to true
+  # @since 0.6.0
+  def before_any(val) insertion(val, 0, true) end
+    
+  # Alias for {#after} with +recursive+ set to true
+  # @since 0.6.0
+  def after_any(val) insertion(val, 1, true) end
+
+  private
+
+  # This method performs the actual insertion
+  # 
+  # @param [Object] val the value to insert
+  # @param [Fixnum] rel the relative index (0 or 1) of where the object
+  #   should be placed
+  # @param [Boolean] recursive look inside sublists
+  # @param [Array] list the list to place objects into
+  def insertion(val, rel, recursive = false, list = @list)
+    if recursive
+      list.each do |item|
+        next unless item.is_a?(Array)
+        tmp = item.dup
+        insertion(val, rel, recursive, item)
+        return(list) unless item == tmp
+      end
+    end
+    
+    if index = list.index(val)
+      list[index+rel,0] = @values
+    end
+    list
+  end
+end

data/lib/yard/docstring.rb

@@ -26,8 +26,10 @@ module YARD
     attr_reader :all
 
     # Matches a tag at the start of a comment line
-    META_MATCH = /^@([a-z_]+)(?:\s+(.*))?$/i
+    META_MATCH = /^@([a-z_0-9]+)(?:\s+(.*))?$/i
     
+    # @group Creating a Docstring Object
+
     # Creates a new docstring with the raw contents attached to an optional
     # object.
     # 
@@ -45,6 +47,20 @@ module YARD
       self.all = content
     end
     
+    # Adds another {Docstring}, copying over tags.
+    # 
+    # @param [Docstring, String] other the other docstring (or string) to
+    #   add.
+    # @return [Docstring] a new docstring with both docstrings combines
+    def +(other)
+      case other
+      when Docstring
+        Docstring.new([all, other.all].join("\n"), object)
+      else
+        super
+      end
+    end
+    
     # Replaces the docstring with new raw content. Called by {#all=}.
     # @param [String] content the raw comments to be parsed
     def replace(content)
@@ -53,6 +69,8 @@ module YARD
       super parse_comments(content)
     end
     alias all= replace
+
+    # @endgroup
     
     # @return [Fixnum] the first line of the {#line_range}.
     def line
@@ -83,6 +101,8 @@ module YARD
       @summary += '.' unless @summary.empty?
       @summary
     end
+
+    # @group Creating and Accessing Meta-data
     
     # Adds a tag or reftag object to the tag list
     # @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
@@ -123,7 +143,6 @@ module YARD
       list.select {|tag| tag.tag_name.to_s == name.to_s }
     end
 
-    ##
     # Returns true if at least one tag by the name +name+ was declared
     #
     # @param [String] name the tag name to search for
@@ -132,12 +151,20 @@ module YARD
       tags.any? {|tag| tag.tag_name.to_s == name.to_s }
     end
 
-    # Returns true if the docstring has no content
+    # Returns true if the docstring has no content that is visible to a template.
     #
+    # @param [Boolean] only_visible_tags whether only {Tags::Library.visible_tags}
+    #   should be checked, or if all tags should be considered.
     # @return [Boolean] whether or not the docstring has content
-    def blank?
-      empty? && @tags.empty? && @ref_tags.empty?
+    def blank?(only_visible_tags = true)
+      if only_visible_tags
+        empty? && !tags.any? {|tag| Tags::Library.visible_tags.include?(tag.tag_name.to_sym) }
+      else
+        empty? && @tags.empty? && @ref_tags.empty?
+      end
     end
+    
+    # @endgroup
 
     private
     
@@ -198,8 +225,8 @@ module YARD
         empty = (line =~ /^\s*$/ ? true : false)
         done = comments.size == index
 
-        if tag_name && (((indent < orig_indent && !empty) || done) || 
-            (indent <= last_indent && line =~ META_MATCH))
+        if tag_name && (((indent < orig_indent && !empty) || done || 
+            (indent == 0 && !empty)) || (indent <= last_indent && line =~ META_MATCH))
           create_tag(tag_name, tag_buf.join("\n"))
           tag_name, tag_buf, = nil, []
           orig_indent = 0

data/lib/yard/globals.rb

@@ -1,9 +1,9 @@
-# Global methods
+# @group Global Convenience Methods
 
 # Shortcut for creating a YARD::CodeObjects::Proxy via a path
 # 
 # @see YARD::CodeObjects::Proxy
-# @see YARD::Registry#resolve
+# @see YARD::Registry.resolve
 def P(namespace, name = nil)
   namespace, name = nil, namespace if name.nil?
   YARD::Registry.resolve(namespace, name, false, true)

data/lib/yard/handlers/base.rb

@@ -11,8 +11,6 @@ module YARD
       def initialize(object) @object = object end
     end
     
-    # = Handlers 
-    # 
     # Handlers are pluggable semantic parsers for YARD's code generation 
     # phase. They allow developers to control what information gets 
     # generated by YARD, giving them the ability to, for instance, document
@@ -188,18 +186,35 @@ module YARD
           (@handlers ||= []).push(*matches)
         end
         
+        # This class is implemented by {Ruby::Base} and {Ruby::Legacy::Base}.
+        # To implement a base handler class for another language, implement
+        # this method to return true if the handler should process the given
+        # statement object. Use {handlers} to enumerate the matchers declared
+        # for the handler class.
+        # 
+        # @param statement a statement object or node (depends on language type)
+        # @return [Boolean] whether or not this handler object should process
+        #   the given statement
         def handles?(statement)
           raise NotImplementedError, "override #handles? in a subclass"
         end
         
+        # @return [Array] a list of matchers for the handler object.
+        # @see handles?
         def handlers
           @handlers ||= []
         end
         
+        # Declares that the handler should only be called when inside a
+        # {CodeObjects::NamespaceObject}, not a method body.
+        # 
+        # @return [void]
         def namespace_only
           @namespace_only = true
         end
         
+        # @return [Boolean] whether the handler should only be processed inside
+        #   a namespace.
         def namespace_only?
           (@namespace_only ||= false) ? true : false
         end
@@ -211,6 +226,7 @@ module YARD
         # 
         # @see #process
         # @return [void]
+        # @since 0.5.4
         def process(&block)
           mod = Module.new
           mod.send(:define_method, :process, &block)
@@ -243,14 +259,36 @@ module YARD
         raise NotImplementedError, "#{self} did not implement a #process method for handling."
       end
       
+      # Parses the semantic "block" contained in the statement node.
+      # 
+      # @abstract Subclasses should call {Processor#process parser.process}
       def parse_block(*args)
         raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
       end
       
       protected
       
-      attr_reader :parser, :statement
-      attr_accessor :owner, :namespace, :visibility, :scope
+      # @return [Processor] the processor object that manages all global state 
+      #   during handling.
+      attr_reader :parser
+      
+      # @return [Object] the statement object currently being processed. Usually
+      #   refers to one semantic language statement, though the strict definition
+      #   depends on the parser used.
+      attr_reader :statement
+      
+      # (see Processor#owner)
+      attr_accessor :owner
+      
+      # (see Processor#namespace)
+      attr_accessor :namespace
+      
+      # (see Processor#visibility)
+      attr_accessor :visibility
+      
+      # (see Processor#scope)
+      attr_accessor :scope
+      
       undef owner, owner=, namespace, namespace=
       undef visibility, visibility=, scope, scope=
       
@@ -263,30 +301,37 @@ module YARD
       def scope; parser.scope end
       def scope=(v); parser.scope=(v) end
       
+      # Executes a given block with specific state values for {#owner},
+      # {#namespace} and {#scope}.
+      # 
+      # @param [Proc] block the block to execute with specific state
+      # @option opts [CodeObjects::NamespaceObject] :namespace (value of #namespace) 
+      #   the namespace object that {#namespace} will be equal to for the
+      #   duration of the block. 
+      # @option opts [Symbol] :scope (:instance) 
+      #   the scope for the duration of the block.
+      # @option opts [CodeObjects::Base] :owner (value of #owner) 
+      #   the owner object (method) for the duration of the block
+      # @yield a block to execute with the given state values.
       def push_state(opts = {}, &block)
         opts = {
-          :namespace => nil,
+          :namespace => namespace,
           :scope => :instance,
-          :owner => nil
+          :owner => owner || namespace
         }.update(opts)
 
-        if opts[:namespace]
-          ns, vis, sc = namespace, visibility, scope
-          self.namespace = opts[:namespace]
-          self.visibility = :public
-          self.scope = opts[:scope]
-        end
+        ns, vis, sc, oo = namespace, visibility, scope, owner
+        self.namespace = opts[:namespace]
+        self.visibility = :public
+        self.scope = opts[:scope]
+        self.owner = opts[:owner]
 
-        oldowner, self.owner = self.owner, opts[:owner] ? opts[:owner] : namespace
         yield
-        self.owner = oldowner
 
-        if opts[:namespace]
-          self.namespace = ns
-          self.owner = namespace
-          self.visibility = vis
-          self.scope = sc
-        end
+        self.namespace = ns
+        self.visibility = vis
+        self.scope = sc
+        self.owner = oo
       end
       
       # Do some post processing on a list of code objects. 
@@ -324,6 +369,22 @@ module YARD
           object.docstring = statement.comments if statement.comments
           object.docstring.line_range = statement.comments_range
           
+          # Add group information
+          if statement.group
+            unless object.namespace.is_a?(Proxy)
+              object.namespace.groups |= [statement.group]
+            end
+            object.group = statement.group
+          end
+          
+          # Add transitive tags
+          Tags::Library.transitive_tags.each do |tag|
+            next if object.namespace.is_a?(Proxy)
+            next unless object.namespace.has_tag?(tag)
+            next if object.has_tag?(tag)
+            object.docstring.add_tag(*object.namespace.tags(tag))
+          end
+          
           # Add source only to non-class non-module objects
           unless object.is_a?(NamespaceObject)
             object.source ||= statement
@@ -336,6 +397,26 @@ module YARD
         objects.size == 1 ? objects.first : objects
       end
 
+      # Ensures that a specific +object+ has been parsed and loaded into the
+      # registry. This is necessary when adding data to a namespace, for instance,
+      # since the namespace may not have been processed yet (it can be located
+      # in a file that has not been handled). 
+      # 
+      # Calling this method defers the handler until all other files have been 
+      # processed. If the object gets resolved, the rest of the handler continues,
+      # otherwise an exception is raised.
+      # 
+      # @example Adding a mixin to the String class programmatically
+      #   ensure_loaded! P('String')
+      #   # "String" is now guaranteed to be loaded
+      #   P('String').mixins << P('MyMixin')
+      # 
+      # @param [Proxy, CodeObjects::Base] object the object to resolve.
+      # @param [Integer] max_retries the number of times to defer the handler
+      #   before raising a +NamespaceMissingError+.
+      # @raise [NamespaceMissingError] if the object is not resolved within
+      #   +max_retries+ attempts, this exception is raised and the handler
+      #   finishes processing.
       def ensure_loaded!(object, max_retries = 1)
         return if object.root?
         unless parser.load_order_errors