yard 0.6.8 → 0.7.0

data/lib/yard/handlers/ruby/class_handler.rb

@@ -1,9 +1,9 @@
 # Handles class declarations
 class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
   include YARD::Handlers::Ruby::StructHandlerMethods
-  namespace_only
   handles :class, :sclass
-  
+  namespace_only
+
   process do
     if statement.type == :class
       classname = statement[0].source
@@ -24,7 +24,7 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
         create_attributes(klass, members_from_tags(klass))
       end
       parse_block(statement[2], :namespace => klass)
-       
+
       if undocsuper
         raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
       end
@@ -56,9 +56,9 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
       raise YARD::Parser::UndocumentableError, "class: #{statement.source[0..sig_end]}"
     end
   end
-  
+
   private
-  
+
   # Extract the parameters from the Struct.new AST node, returning them as a list
   # of strings
   #
@@ -69,7 +69,7 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
     members.map! {|x| x.source.strip[1..-1]}
     members
   end
-  
+
   def create_struct_superclass(superclass, superclass_def)
     return if superclass == "Struct"
     the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
@@ -78,7 +78,7 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
     parse_struct_superclass(the_super, superclass_def)
     the_super
   end
-  
+
   def struct_superclass_name(superclass)
     if superclass.call?
       first = superclass.parameters.first
@@ -88,16 +88,16 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
     end
     "Struct"
   end
-  
+
   def parse_struct_superclass(klass, superclass)
     return unless superclass.call? && superclass.parameters
     members = extract_parameters(superclass)
     create_attributes(klass, members)
   end
-  
+
   def parse_superclass(superclass)
     return nil unless superclass
-    
+
     case superclass.type
     when :var_ref
       return namespace.path if superclass.first == s(:kw, "self")

data/lib/yard/handlers/ruby/class_variable_handler.rb

@@ -1,13 +1,13 @@
 # Handles a class variable (@@variable)
 class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
-  namespace_only
   handles :assign
-  
+  namespace_only
+
   process do
     if statement[0].type == :var_field && statement[0][0].type == :cvar
       name = statement[0][0][0]
       value = statement[1].source
-      register ClassVariableObject.new(namespace, name) do |o| 
+      register ClassVariableObject.new(namespace, name) do |o|
         o.source = statement
         o.value = value
       end

data/lib/yard/handlers/ruby/constant_handler.rb

@@ -1,26 +1,26 @@
 # Handles any constant assignment
 class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
   include YARD::Handlers::Ruby::StructHandlerMethods
-  namespace_only
   handles :assign
-  
+  namespace_only
+
   process do
-    if statement[1].call? && statement[1][0][0] == s(:const, "Struct") && 
+    if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
         statement[1][2] == s(:ident, "new")
       process_structclass(statement)
     elsif statement[0].type == :var_field && statement[0][0].type == :const
       process_constant(statement)
     end
   end
-  
+
   private
-  
+
   def process_constant(statement)
     name = statement[0][0][0]
     value = statement[1].source
     register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
   end
-  
+
   def process_structclass(statement)
     lhs = statement[0][0]
     if lhs.type == :const
@@ -30,7 +30,7 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
       raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
     end
   end
-  
+
   # Extract the parameters from the Struct.new AST node, returning them as a list
   # of strings
   #

data/lib/yard/handlers/ruby/exception_handler.rb

@@ -1,7 +1,7 @@
 # Handles 'raise' calls inside methods
 class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
   handles method_call(:raise)
-  
+
   process do
     return unless owner.is_a?(MethodObject) # Only methods yield
     return if [:command_call, :call].include? statement.type
@@ -9,7 +9,7 @@ class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
 
     klass = nil
     params = statement.parameters(false)
-    if params.size == 1 
+    if params.size == 1
       if params.first.ref? && params.first.first.type != :ident
         klass = params.first.source
       elsif params.first.call? && params.first.method_name(true) == :new

data/lib/yard/handlers/ruby/extend_handler.rb

@@ -1,8 +1,8 @@
 # Handles 'extend' call to include modules into the class scope of another
 # @see MixinHandler
 class YARD::Handlers::Ruby::ExtendHandler < YARD::Handlers::Ruby::MixinHandler
-  namespace_only
   handles method_call(:extend)
+  namespace_only
 
   def scope; :class end
 

data/lib/yard/handlers/ruby/legacy/alias_handler.rb

@@ -1,22 +1,23 @@
 # (see Ruby::AliasHandler)
 class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aalias(_method)?(\s|\()/
-  
+  namespace_only
+
   process do
-    if TkALIAS === statement.tokens.first 
+    if TkALIAS === statement.tokens.first
       tokens = statement.tokens[2..-1].to_s.split(/\s+/)
       names = [tokens[0], tokens[1]].map {|t| t.gsub(/^:(['"])?(.+?)\1?$|^(:)(.+)/, '\2') }
     else
       names = tokval_list(statement.tokens[2..-1], :attr)
     end
     raise YARD::Parser::UndocumentableError, statement.tokens.first.text if names.size != 2
-    
+
     new_meth, old_meth = names[0].to_sym, names[1].to_sym
     old_obj = namespace.child(:name => old_meth, :scope => scope)
     new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
       o.visibility = visibility
       o.scope = scope
-      o.add_file(parser.file, statement.tokens.first.line_no)
+      o.add_file(parser.file, statement.tokens.first.line_no, statement.comments)
       o.docstring = statement.comments
     end
 
@@ -24,11 +25,13 @@ class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy:
       new_obj.signature = old_obj.signature
       new_obj.source = old_obj.source
       new_obj.docstring = old_obj.docstring + YARD::Docstring.new(statement.comments)
+      new_obj.docstring.line_range = statement.comments_range
+      new_obj.docstring.hash_flag = statement.comments_hash_flag
       new_obj.docstring.object = new_obj
     else
       new_obj.signature = "def #{new_meth}" # this is all we know.
     end
-    
+
     namespace.aliases[new_obj] = old_meth
   end
 end

data/lib/yard/handlers/ruby/legacy/attribute_handler.rb

@@ -1,7 +1,8 @@
 # (see Ruby::AttributeHandler)
 class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aattr(?:_(?:reader|writer|accessor))?(?:\s|\()/
-  
+  namespace_only
+
   process do
     begin
       attr_type   = statement.tokens.first.text.to_sym
@@ -10,7 +11,7 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
     rescue SyntaxError
       raise YARD::Parser::UndocumentableError, attr_type
     end
-    
+
     # Change read/write based on attr_reader/writer/accessor
     case attr_type
     when :attr
@@ -25,9 +26,9 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
     end
 
     # Add all attributes
-    symbols.each do |name| 
+    symbols.each do |name|
       namespace.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]
-      
+
       # Show their methods as well
       {:read => name, :write => "#{name}="}.each do |type, meth|
         if (type == :read ? read : write)
@@ -47,7 +48,7 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
             o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
             o.visibility = visibility
           end
-        
+
           # Register the objects explicitly
           register namespace.attributes[scope][name][type]
         elsif obj = namespace.children.find {|o| o.name == meth.to_sym && o.scope == scope }

data/lib/yard/handlers/ruby/legacy/base.rb

@@ -3,12 +3,12 @@ module YARD
     module Ruby::Legacy
       # This is the base handler for the legacy parser. To implement a legacy
       # handler, subclass this class.
-      # 
+      #
       # @abstract (see Ruby::Base)
       class Base < Handlers::Base
         # For tokens like TkDEF, TkCLASS, etc.
         include YARD::Parser::Ruby::Legacy::RubyToken
-        
+
         # @return [Boolean] whether or not a {Parser::Ruby::Legacy::Statement} object should be handled
         #   by this handler.
         def self.handles?(stmt)
@@ -19,17 +19,17 @@ module YARD
             when Regexp
               stmt.tokens.to_s =~ a_handler
             else
-              a_handler == stmt.tokens.first.class 
+              a_handler == stmt.tokens.first.class
             end
           end
         end
 
         protected
 
-        # Parses a statement's block with a set of state values. If the 
+        # Parses a statement's block with a set of state values. If the
         # statement has no block, nothing happens. A description of state
         # values can be found at {Handlers::Base#push_state}
-        # 
+        #
         # @param [Hash] opts State options
         # @option opts (see Handlers::Base#push_state)
         # @see Handlers::Base#push_state #push_state
@@ -42,37 +42,52 @@ module YARD
           end
         end
         
+        def call_params
+          tokens = statement.tokens[1..-1]
+          tokval_list(tokens, :attr, :identifier, TkId).map do |value|
+            value.to_s
+          end
+        end
+
+        def caller_method
+          if statement.tokens.first.is_a?(TkIDENTIFIER)
+            statement.tokens.first.text
+          else
+            nil
+          end
+        end
+
         private
-      
-        # The string value of a token. For example, the return value for the symbol :sym 
-        # would be :sym. The return value for a string +"foo #{ bar}"+ would be the literal 
+
+        # The string value of a token. For example, the return value for the symbol :sym
+        # would be :sym. The return value for a string +"foo #{ bar}"+ would be the literal
         # +"foo #{ bar}"+ without any interpolation. The return value of the identifier
         # 'test' would be the same value: 'test'. Here is a list of common types and
         # their return values:
-        # 
-        # @example 
+        #
+        # @example
         #   tokval(TokenList.new('"foo"').first) => "foo"
         #   tokval(TokenList.new(':foo').first) => :foo
         #   tokval(TokenList.new('CONSTANT').first, RubyToken::TkId) => "CONSTANT"
         #   tokval(TokenList.new('identifier').first, RubyToken::TkId) => "identifier"
         #   tokval(TokenList.new('3.25').first) => 3.25
         #   tokval(TokenList.new('/xyz/i').first) => /xyz/i
-        # 
+        #
         # @param [Token] token The token of the class
-        # 
+        #
         # @param [Array<Class<Token>>, Symbol] accepted_types
         #   The allowed token types that this token can be. Defaults to [{TkVal}].
         #   A list of types would be, for example, [+TkSTRING+, +TkSYMBOL+], to return
-        #   the token's value if it is either of those types. If +TkVal+ is accepted, 
+        #   the token's value if it is either of those types. If +TkVal+ is accepted,
         #   +TkNode+ is also accepted.
-        # 
+        #
         #   Certain symbol keys are allowed to specify multiple types in one fell swoop.
         #   These symbols are:
         #     :string       => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+
         #     :attr         => +TkSYMBOL+ and +TkSTRING+
         #     :identifier   => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.
         #     :number       => +TkFLOAT+, +TkINTEGER+
-        # 
+        #
         # @return [Object] if the token is one of the accepted types, in its real value form.
         #   It should be noted that identifiers and constants are kept in String form.
         # @return [nil] if the token is not any of the specified accepted types
@@ -99,7 +114,7 @@ module YARD
           return unless accepted_types.any? {|t| t === token }
 
           case token
-          when TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING 
+          when TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING
             token.text[1..-2]
           when TkSYMBOL
             token.text[1..-1].to_sym
@@ -121,26 +136,26 @@ module YARD
           end
         end
 
-        # Returns a list of symbols or string values from a statement. 
-        # The list must be a valid comma delimited list, and values 
+        # Returns a list of symbols or string values from a statement.
+        # The list must be a valid comma delimited list, and values
         # will only be returned to the end of the list only.
-        # 
+        #
         # Example:
         #   attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']
-        #   attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c'] 
-        # 
+        #   attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c']
+        #
         # The tokval list of a {Parser::Ruby::Legacy::TokenList} of the above
         # code would be the {#tokval} value of :a, 'b',
         # :c and :d.
-        # 
+        #
         # It should also be noted that this function stops immediately at
         # any ruby keyword encountered:
         #   "attr_accessor :a, :b, :c if x == 5"  => ['a', 'b', 'c']
-        # 
+        #
         # @param [TokenList] tokenlist The list of tokens to process.
         # @param [Array<Class<Token>>] accepted_types passed to {#tokval}
         # @return [Array<String>] the list of tokvalues in the list.
-        # @return [Array<EMPTY>] if there are no symbols or Strings in the list 
+        # @return [Array<EMPTY>] if there are no symbols or Strings in the list
         # @see #tokval
         def tokval_list(tokenlist, *accepted_types)
           return [] unless tokenlist
@@ -176,7 +191,7 @@ module YARD
                 parencount -= 1
               end
             when TkLBRACE, TkLBRACK, TkDO
-              parencount += 1 
+              parencount += 1
               out.last << token.text if tokval != nil
             when TkRBRACE, TkRBRACK, TkEND
               out.last << token.text if tokval != nil
@@ -186,14 +201,14 @@ module YARD
 
               seen_comma = false unless TkWhitespace === token
               if parencount == 0
-                next if needcomma 
+                next if needcomma
                 next if TkWhitespace === token
                 if tokval != nil
                   out.last << tokval
                 else
                   out.last.clear
                   needcomma = true
-                end 
+                end
               elsif parencond
                 needcomma = true
                 out.last << token.text

data/lib/yard/handlers/ruby/legacy/class_condition_handler.rb

@@ -3,7 +3,7 @@
 class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby::Legacy::Base
   namespace_only
   handles TkIF, TkELSIF, TkUNLESS
-  
+
   process do
     condition = parse_condition
     if condition == nil
@@ -16,25 +16,25 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
       parse_else_block
     end
   end
-  
+
   protected
-  
+
   # Parses the condition part of the if/unless statement
-  # 
+  #
   # @return [true, false, nil] true if the condition can be definitely
   #   parsed to true, false if not, and nil if the condition cannot be
   #   parsed with certainty (it's dynamic)
   # @since 0.5.5
   def parse_condition
     condition = nil
-    
+
     # Right now we can handle very simple unary conditions like:
     #   if true
     #   if false
     #   if 0
     #   if 100 (not 0)
     #   if defined? SOME_CONSTANT
-    # 
+    #
     # The last case will do a lookup in the registry and then one
     # in the Ruby world (using eval).
     case statement.tokens[1..-1].to_s.strip
@@ -56,18 +56,18 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
     when "false"
       condition = false
     end
-    
+
     if TkUNLESS === statement.tokens.first
       condition = !condition if condition != nil
     end
     condition
   end
-  
+
   # @since 0.5.5
   def parse_then_block
     parse_block
   end
-  
+
   # @since 0.5.5
   def parse_else_block
     return unless statement.block