yard 0.2.3.5 → 0.4.0

data/lib/yard/core_ext/file.rb

@@ -1,18 +1,16 @@
 class File
   RELATIVE_PARENTDIR = '..'
+  RELATIVE_SAMEDIR = '.'
   
   # 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
-  # ends in `File::SEPARATOR` ('/' on UNIX filesystems).
+  # ends in +File::SEPARATOR+ ('/' on UNIX filesystems).
   # 
   # @param [String] from the starting filename 
   #   (or directory with +from_isdir+ set to +true+).
-  # 
   # @param [String] to the final path that should be made relative.
-  # 
   # @return [String] the relative path from +from+ to +to+.
-  # 
   def self.relative_path(from, to)
     from = expand_path(from).split(SEPARATOR)
     to = expand_path(to).split(SEPARATOR)
@@ -23,4 +21,23 @@ class File
     fname = from.pop
     join *(from.map { RELATIVE_PARENTDIR } + to)
   end
+  
+  # Cleans a path by removing extraneous '..', '.' and '/' characters
+  # 
+  # @example Clean a path
+  #   File.cleanpath('a/b//./c/../e') # => "a/b/e"
+  # @param [String] path the path to clean
+  # @return [String] the sanitized path
+  def self.cleanpath(path)
+    path = path.split(SEPARATOR)
+    path = path.inject([]) do |acc, comp|
+      next acc if comp == RELATIVE_SAMEDIR
+      if comp == RELATIVE_PARENTDIR && acc.size > 0
+        acc.pop
+        next acc
+      end
+      acc << comp
+    end
+    File.join(*path)
+  end
 end

data/lib/yard/core_ext/module.rb

@@ -1,8 +1,18 @@
 class Module
+  # Returns the class name of a full module namespace path
+  # 
+  # @example
+  #   module A::B::C; class_name end # => "C"
+  # @return [String] the last part of a module path
   def class_name
     name.split("::").last
   end
-  
+
+  # Returns the module namespace path minus the class/module name
+  # 
+  # @example
+  #   module A::B::C; namespace end # => "A::B"
+  # @return [String] the namespace minus the class/module name
   def namespace
     name.split("::")[0..-2].join("::")
   end

data/lib/yard/core_ext/string.rb

@@ -1,9 +1,20 @@
 class String
+  # Separates capital letters following lower case letters by an underscore
+  # and returns the entire string in lower case
+  # 
+  # @example
+  #   "FooBar".underscore # => "foo_bar"
+  # @return [String] the underscored lower case string
   def underscore
-    gsub(/([a-z])([A-Z])/, '\1_\2').downcase 
+    gsub(/([a-z])([A-Z])/, '\1_\2').downcase.gsub('::', '/')
   end
   
+  # Camel cases any underscored text.
+  # 
+  # @example
+  #   "foo_bar_baz".camelcase # => "FooBarBaz"
+  # @return [String] the camel cased text
   def camelcase
-    gsub(/([a-z])_([a-z])/i) { $1 + $2.upcase }.sub(/^(.)/) { $1.upcase } 
+    gsub(/([a-z])_([a-z])/i) { $1 + $2.upcase }.sub(/^(.)/) { $1.upcase }.gsub('/', '::') 
   end
 end

data/lib/yard/core_ext/symbol_hash.rb

@@ -1,8 +1,29 @@
+# A subclass of Hash where all keys are converted into Symbols, and 
+# optionally, all String values are converted into Symbols.
 class SymbolHash < Hash
+  # Creates a new SymbolHash object
+  # 
+  # @param [Boolean] symbolize_value converts any String values into Symbols
+  #   if this is set to +true+.
   def initialize(symbolize_value = true)
     @symbolize_value = symbolize_value
   end
-  
+
+  # @overload [](hash)
+  #   Creates a SymbolHash object from an existing Hash
+  #   
+  #   @example
+  #     SymbolHash['x' => 1, :y => 2] # => #<SymbolHash:0x...>
+  #   @param [Hash] hash the hash object
+  #   @return [SymbolHash] a new SymbolHash from a hash object
+  # 
+  # @overload [](*list)
+  #   Creates a SymbolHash from an even list of keys and values
+  #   
+  #   @example
+  #     SymbolHash[key1, value1, key2, value2, ...]
+  #   @param [Array] list an even list of key followed by value
+  #   @return [SymbolHash] a new SymbolHash object
   def self.[](*hsh)
     obj = new;
     if hsh.size == 1 && hsh.first.is_a?(Hash)
@@ -13,13 +34,40 @@ class SymbolHash < Hash
     obj
   end
   
+  # Assigns a value to a symbolized key
+  # @param [#to_sym] key the key
+  # @param [Object] value the value to be assigned. If this is a String and
+  #   values are set to be symbolized, it will be converted into a Symbol.
   def []=(key, value) 
     super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value) 
   end
+  
+  # Accessed a symbolized key
+  # @param [#to_sym] key the key to access
+  # @return [Object] the value associated with the key
   def [](key) super(key.to_sym) end
+    
+  # Deleted a key and value associated with it
+  # @param [#to_sym] key the key to delete
+  # @return [nil]
   def delete(key) super(key.to_sym) end
+    
+  # Tests if a symbolized key exists
+  # @param [#to_sym] key the key to test
+  # @return [Boolean] whether the key exists
   def has_key?(key) super(key.to_sym) end
-  def update(hsh) hsh.each {|k,v| self[k] = v }; self end
+    
+  # Updates the object with the contents of another Hash object
+  # This method modifies the original SymbolHash object
+  # 
+  # @param [Hash] hash the hash object to copy the values from
+  # @return [SymbolHash] self
+  def update(hash) hash.each {|k,v| self[k] = v }; self end
   alias_method :merge!, :update
-  def merge(hsh) dup.merge!(hsh) end
+
+  # Merges the contents of another hash into a new SymbolHash object
+  # 
+  # @param [Hash] hash the hash of objects to copy
+  # @return [SymbolHash] a new SymbolHash containing the merged data
+  def merge(hash) dup.merge!(hash) end
 end

data/lib/yard/docstring.rb

@@ -1,10 +1,43 @@
 module YARD
+  # A documentation string, or "docstring" for short, encapsulates the 
+  # comments and metadata, or "tags", of an object. Meta-data is expressed
+  # in the form +@tag VALUE+, where VALUE can span over multiple lines as
+  # long as they are indented. The following +@example+ tag shows how tags
+  # can be indented:
+  # 
+  #   # @example My example
+  #   #   a = "hello world"
+  #   #   a.reverse
+  #   # @version 1.0
+  # 
+  # Tags can be nested in a documentation string, though the {Tags::Tag} 
+  # itself is responsible for parsing the inner tags.
   class Docstring < String
+    # @return [Array<Tags::RefTag>] the list of reference tags
     attr_reader :ref_tags
-    attr_accessor :object, :line_range, :all
+    
+    # @return [CodeObjects::Base] the object that owns the docstring.
+    attr_accessor :object
+    
+    # @return [Range] line range in the {#object}'s file where the docstring was parsed from
+    attr_accessor :line_range
+    
+    # @return [String] the raw documentation (including raw tag text)
+    attr_accessor :all
 
+    # Matches a tag at the start of a comment line
     META_MATCH = /^@([a-z_]+)(?:\s+(.*))?$/i
     
+    # Creates a new docstring with the raw contents attached to an optional
+    # object.
+    # 
+    # @example
+    #   Docstring.new("hello world\n@return Object return", someobj)
+    # 
+    # @param [String] content the raw comments to be parsed into a docstring
+    #   and associated meta-data.
+    # @param [CodeObjects::Base] object an object to associate the docstring
+    #   with.
     def initialize(content = '', object = nil)
       @tag_factory = Tags::Library.new
       @object = object
@@ -12,6 +45,8 @@ module YARD
       self.all = content
     end
     
+    # Replaces the docstring with new raw content. Called by {#all=}.
+    # @param [String] content the raw comments to be parsed
     def replace(content)
       @tags, @ref_tags = [], []
       @all = content
@@ -19,25 +54,38 @@ module YARD
     end
     alias all= replace
     
+    # @return [Fixnum] the first line of the {#line_range}.
     def line
       line_range.first
     end
     
-    ##
     # Gets the first line of a docstring to the period or the first paragraph.
-    # 
     # @return [String] The first line or paragraph of the docstring; always ends with a period.
     def summary
       return @summary if @summary
-      summary = split(/\.|\r?\n\r?\n/).first || ''
-      summary += '.' unless summary.empty?
-      @summary = summary
+      open_parens = ['{', '(', '[']
+      close_parens = ['}', ')', ']']
+      num_parens = 0
+      idx = length.times do |index|
+        case self[index, 1]
+        when ".", "\r", "\n"
+          next_char = self[index + 1, 1].to_s
+          if num_parens == 0 && next_char =~ /^\s*$/
+            break index - 1
+          end
+        when "{", "(", "["
+          num_parens += 1
+        when "}", ")", "]"
+          num_parens -= 1
+        end
+      end
+      @summary = self[0..idx]
+      @summary += '.' unless @summary.empty?
+      @summary
     end
     
-    ##
     # Adds a tag or reftag object to the tag list
-    # 
-    # @param [Tags::Tag, Tags::RefTag] *tags list of tag objects to add
+    # @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
     def add_tag(*tags)
       tags.each_with_index do |tag, i|
         case tag
@@ -52,12 +100,11 @@ module YARD
       end
     end
     
-    ## 
     # Convenience method to return the first tag
     # object in the list of tag objects of that name
     #
     # @example
-    #   doc = YARD::Docstring.new("@return zero when nil")
+    #   doc = Docstring.new("@return zero when nil")
     #   doc.tag(:return).text  # => "zero when nil"
     #
     # @param [#to_s] name the tag name to return data for
@@ -66,10 +113,9 @@ module YARD
       tags.find {|tag| tag.tag_name.to_s == name.to_s }
     end
 
-    ##
     # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
     #
-    # @param name the tag name to return data for, or nil for all tags
+    # @param [#to_s] name the tag name to return data for, or nil for all tags
     # @return [Array<Tags::Tag>] the list of tags by the specified tag name
     def tags(name = nil)
       list = @tags + convert_ref_tags
@@ -86,7 +132,6 @@ module YARD
       tags.any? {|tag| tag.tag_name.to_s == name.to_s }
     end
 
-    ##
     # Returns true if the docstring has no content
     #
     # @return [Boolean] whether or not the docstring has content
@@ -96,20 +141,25 @@ module YARD
 
     private
     
+    # Maps valid reference tags
+    # 
+    # @return [Array<Tags::RefTag>] the list of valid reference tags
     def convert_ref_tags
       list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }
       list.map {|t| t.tags }.flatten
     end
     
-    ##
-    # Creates a {RefTag}
+    # Creates a {Tags::RefTag}
     def create_ref_tag(tag_name, name, object)
       @ref_tags << Tags::RefTagList.new(tag_name, object, name)
     end
     
-    ##
-    # Creates a tag from the TagFactory 
+    # Creates a tag from the {Tags::DefaultFactory tag factory}.
     # 
+    # @param [String] tag_name the tag name
+    # @param [String] tag_buf the text attached to the tag with newlines removed.
+    # @param [String] raw_buf the raw buffer of text without removed newlines.
+    # @return [Tags::Tag, Tags::RefTag] a tag
     def create_tag(tag_name, tag_buf, raw_buf)
       if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
         return create_ref_tag(tag_name, $1, $2)
@@ -129,7 +179,6 @@ module YARD
       log.warn "Invalid tag format for @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
     end
 
-    ##
     # Parses out comments split by newlines into a new code object
     #
     # @param [String] comments 

data/lib/yard/globals.rb

@@ -1,7 +1,6 @@
 # Global methods
 
-# Shortcut for creating a YARD::CodeObjects::Proxy 
-# via a path
+# Shortcut for creating a YARD::CodeObjects::Proxy via a path
 # 
 # @see YARD::CodeObjects::Proxy
 # @see YARD::Registry#resolve
@@ -10,6 +9,10 @@ def P(namespace, name = nil)
   YARD::Registry.resolve(namespace, name, false, true)
 end
 
+# The global {YARD::Logger} instance
+# 
+# @return [YARD::Logger] the global {YARD::Logger} instance
+# @see YARD::Logger
 def log
   YARD::Logger.instance
 end

data/lib/yard/handlers/base.rb

@@ -1,7 +1,13 @@
 module YARD
   module Handlers
+    # Raised during processing phase when a handler needs to perform
+    # an operation on an object's namespace but the namespace could
+    # not be resolved.
     class NamespaceMissingError < Parser::UndocumentableError
+      # The object the error occured on
+      # @return [CodeObjects::Base] a code object
       attr_accessor :object
+      
       def initialize(object) @object = object end
     end
     
@@ -125,6 +131,9 @@ module YARD
     # even if statements. For this reason, the block parsing method must be 
     # invoked explicitly out of efficiency sake.
     # 
+    # @abstract Subclass this class to provide a handler for YARD to use
+    #   during the processing phase.
+    # 
     # @see CodeObjects::Base
     # @see CodeObjects::NamespaceObject
     # @see handles
@@ -132,7 +141,6 @@ module YARD
     # @see #owner
     # @see #register
     # @see #parse_block
-    #
     class Base 
       # For accessing convenience, eg. "MethodObject" 
       # instead of the full qualified namespace
@@ -141,10 +149,14 @@ module YARD
       include Parser
       
       class << self
+        # Clear all registered subclasses. Testing purposes only
+        # @return [nil] 
         def clear_subclasses
           @@subclasses = []
         end
         
+        # Returns all registered handler subclasses.
+        # @return [Array<Base>] a list of handlers
         def subclasses
           @@subclasses ||= []
         end
@@ -335,8 +347,6 @@ module YARD
           else
             raise NamespaceMissingError, object
           end
-        else
-          log.debug "Object #{object} successfully resolved. Adding children."
         end
         object
       end

data/lib/yard/handlers/processor.rb

@@ -1,9 +1,52 @@
 module YARD
   module Handlers
+    # Iterates over all statements in a file and delegates them to the 
+    # {Handlers::Base} objects that are registered to handle the statement.
+    # 
+    # This class is passed to each handler and keeps overall processing state.
+    # For example, if the {#visibility} is set in a handler, all following
+    # statements will have access to this state. This allows "public", 
+    # "protected" and "private" statements to be handled in classes and modules.
+    # In addition, the {#namespace} can be set during parsing to control
+    # where objects are being created from.
+    # 
+    # @see Handlers::Base
     class Processor
-      attr_accessor :file, :namespace, :visibility
-      attr_accessor :scope, :owner, :load_order_errors, :parser_type
+      # @return [String] the filename
+      attr_accessor :file
+
+      # @return [CodeObjects::NamespaceObject] the current namespace
+      attr_accessor :namespace
+      
+      # @return [Symbol] the current visibility
+      attr_accessor :visibility
+      
+      # @return [Symbol] the current scope
+      attr_accessor :scope
+      
+      # @return [CodeObjects::Base, nil] unlike the namespace, the owner
+      #   is a non-namespace object that should be stored between statements.
+      #   For instance, when parsing a method body, the {CodeObjects::MethodObject}
+      #   is set as the owner, in case any extra method information is processed.
+      attr_accessor :owner
+      
+      # @return [Boolean] whether or not {Parser::LoadOrderError} is raised
+      attr_accessor :load_order_errors
+      
+      # @return [Symbol] the parser type (:ruby, :ruby18 or :c)
+      attr_accessor :parser_type
       
+      # Creates a new Processor for a +file+.
+      # 
+      # @param [String] file the name of the file that is being processed.
+      #   uses '(stdin)' if file is nil. 
+      # @param [Boolean] load_order_error whether or not to raise {Parser::LoadOrderError}
+      #   when a file has unresolved references that need to be parsed first.
+      #   If these errors are raised, the processor will attempt to load all 
+      #   other files before continuing to parse the file.
+      # @param [Symbol] parser_type the parser type (:ruby, :ruby18, :c) from
+      #   the parser. Used to select the handler (since handlers are specific
+      #   to a parser type).
       def initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type)
         @file = file || "(stdin)"
         @namespace = YARD::Registry.root
@@ -16,6 +59,11 @@ module YARD
         load_handlers
       end
       
+      # Processes a list of statements by finding handlers to process each
+      # one.
+      # 
+      # @param [Array] statements a list of statements
+      # @return [nil] 
       def process(statements)
         statements.each_with_index do |stmt, index|
           find_handlers(stmt).each do |handler| 
@@ -41,6 +89,10 @@ module YARD
         end
       end
       
+      # Searches for all handlers in {Base.subclasses} that match the +statement+
+      # 
+      # @param statement the statement object to match.
+      # @return [Array<Base>] a list of handlers to process the statement with.
       def find_handlers(statement)
         Base.subclasses.find_all do |handler|
           handler_base_class > handler &&
@@ -51,10 +103,16 @@ module YARD
       
       private
       
+      # Returns the handler base class
+      # @return [Base] the base class
       def handler_base_class
         handler_base_namespace.const_get(:Base)
       end
 
+      # The module holding the handlers to be loaded
+      # 
+      # @return [Module] the module containing the handlers depending on
+      #   {#parser_type}.
       def handler_base_namespace
         case parser_type
         when :ruby;   Ruby
@@ -62,6 +120,10 @@ module YARD
         end
       end
       
+      # Loads handlers from {#handler_base_namespace}. This ensures that
+      # Ruby1.9 handlers are never loaded into 1.8; also lowers the amount
+      # of modules that are loaded
+      # @return [nil]
       def load_handlers
         return if @handlers_loaded[parser_type]
         handler_base_namespace.constants.each {|c| handler_base_namespace.const_get(c) }