yard 0.7.5 → 0.8.0

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

@@ -22,8 +22,6 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
     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.line)
     end
 

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

@@ -33,25 +33,24 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
       # Show their methods as well
       {:read => name, :write => "#{name}="}.each do |type, meth|
         if (type == :read ? read : write)
-          namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
-            if type == :write
-              o.parameters = [['value', nil]]
-              src = "def #{meth}(value)"
-              full_src = "#{src}\n  @#{name} = value\nend"
-              doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
-            else
-              src = "def #{meth}"
-              full_src = "#{src}\n  @#{name}\nend"
-              doc = "Returns the value of attribute #{name}"
-            end
-            o.source ||= full_src
-            o.signature ||= src
-            o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
-            o.visibility = visibility
+          o = MethodObject.new(namespace, meth, scope)
+          if type == :write
+            o.parameters = [['value', nil]]
+            src = "def #{meth}(value)"
+            full_src = "#{src}\n  @#{name} = value\nend"
+            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
+          else
+            src = "def #{meth}"
+            full_src = "#{src}\n  @#{name}\nend"
+            doc = "Returns the value of attribute #{name}"
           end
+          o.source ||= full_src
+          o.signature ||= src
+          register(o)
+          o.docstring = doc if o.docstring.blank?(false)
 
-          # Register the objects explicitly
-          register namespace.attributes[scope][name][type]
+          # Regsiter the object explicitly
+          namespace.attributes[scope][name][type] = o
         elsif obj = namespace.children.find {|o| o.name == meth.to_sym && o.scope == scope }
           # register an existing method as attribute
           namespace.attributes[scope][name][type] = obj

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

@@ -135,21 +135,25 @@ module YARD
             parser.process(nodes)
           end
         end
-        
+
         # @group Macro Handling
 
         def call_params
           return [] unless statement.respond_to?(:parameters)
-          statement.parameters(false).map do |param|
-            param.jump(:ident, :tstring_content).source
-          end
+          statement.parameters(false).compact.map do |param|
+            if param.type == :list
+              param.map {|n| n.jump(:ident, :kw, :tstring_content).source }
+            else
+              param.jump(:ident, :kw, :tstring_content).source
+            end
+          end.flatten
         end
 
         def caller_method
-          if statement.call?
+          if statement.call? || statement.def?
             statement.method_name(true).to_s
           elsif statement.type == :var_ref || statement.type == :vcall
-            statement[0].jump(:ident).source
+            statement[0].jump(:ident, :kw).source
           else
             nil
           end

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

@@ -0,0 +1,9 @@
+# Handles any lone comment statement in a Ruby file
+class YARD::Handlers::Ruby::CommentHandler < YARD::Handlers::Ruby::Base
+  handles :comment, :void_stmt
+  namespace_only
+
+  process do
+    register_docstring(nil)
+  end
+end

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

@@ -0,0 +1,14 @@
+module YARD
+  module Handlers
+    module Ruby
+      # Handles automatic detection of dsl-style methods
+      class DSLHandler < Base
+        include CodeObjects
+        include DSLHandlerMethods
+        handles method_call
+        namespace_only
+        process { handle_comments }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module YARD
+  module Handlers
+    module Ruby
+      module DSLHandlerMethods
+        include CodeObjects
+        include Parser
+
+        IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
+          attr_reader attr_writer extend include public private protected
+          private_constant).map {|n| [n, true] }.flatten]
+
+        def handle_comments
+          return if IGNORE_METHODS[caller_method]
+
+          @docstring = statement.comments || ""
+          @docstring = @docstring.join("\n") if @docstring.is_a?(Array)
+          if macro = find_attached_macro
+            @docstring += "\n" +
+              macro.expand([caller_method, *call_params], statement.source)
+          elsif !statement.comments_hash_flag && !implicit_docstring?
+            return register_docstring(nil)
+          end
+
+          # ignore DSL definitions if @method/@attribute directive is used
+          if @docstring =~ /^@!?(method|attribute)\b/
+            return register_docstring(nil)
+          end
+
+          object = MethodObject.new(namespace, method_name, scope)
+          object.signature = method_signature
+          register(object)
+        end
+
+        def register_docstring(object, docstring = @docstring, stmt = statement)
+          super
+        end
+
+        private
+
+        def implicit_docstring?
+          tags = %w(method attribute overload visibility scope return)
+          tags.any? {|tag| @docstring =~ /^@!?#{tag}\b/ }
+        end
+
+        def method_name
+          name = call_params.first || ""
+          if name =~ /^#{CodeObjects::METHODNAMEMATCH}$/
+            name
+          else
+            raise UndocumentableError, "method, missing name"
+          end
+        end
+
+        def method_signature
+          "def #{method_name}"
+        end
+
+        def find_attached_macro
+          Registry.all(:macro).each do |macro|
+            next unless macro.method_object
+            next unless macro.method_object.name.to_s == caller_method.to_s
+            (namespace.inheritance_tree + [P('Object')]).each do |obj|
+              return macro if obj == macro.method_object.namespace
+            end
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -15,10 +15,7 @@ class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy:
     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, statement.comments)
-      o.docstring = statement.comments
     end
 
     if old_obj

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

@@ -32,25 +32,24 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
       # Show their methods as well
       {:read => name, :write => "#{name}="}.each do |type, meth|
         if (type == :read ? read : write)
-          namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
-            if type == :write
-              o.parameters = [['value', nil]]
-              src = "def #{meth}(value)"
-              full_src = "#{src}\n  @#{name} = value\nend"
-              doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
-            else
-              src = "def #{meth}"
-              full_src = "#{src}\n  @#{name}\nend"
-              doc = "Returns the value of attribute #{name}"
-            end
-            o.source ||= full_src
-            o.signature ||= src
-            o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
-            o.visibility = visibility
+          o = MethodObject.new(namespace, meth, scope)
+          if type == :write
+            o.parameters = [['value', nil]]
+            src = "def #{meth}(value)"
+            full_src = "#{src}\n  @#{name} = value\nend"
+            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
+          else
+            src = "def #{meth}"
+            full_src = "#{src}\n  @#{name}\nend"
+            doc = "Returns the value of attribute #{name}"
           end
+          o.source ||= full_src
+          o.signature ||= src
+          register(o)
+          o.docstring = doc if o.docstring.blank?(false)
 
-          # Register the objects explicitly
-          register namespace.attributes[scope][name][type]
+          # Regsiter the object explicitly
+          namespace.attributes[scope][name][type] = o
         elsif obj = namespace.children.find {|o| o.name == meth.to_sym && o.scope == scope }
           # register an existing method as attribute
           namespace.attributes[scope][name][type] = obj

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

@@ -24,8 +24,6 @@ module YARD
           end
         end
 
-        protected
-
         # 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}
@@ -41,17 +39,23 @@ module YARD
             end
           end
         end
-        
+
         def call_params
-          tokens = statement.tokens[1..-1]
-          tokval_list(tokens, :attr, :identifier, TkId).map do |value|
-            value.to_s
+          if statement.tokens.first.is_a?(TkDEF)
+            extract_method_details.last.map {|param| param.first }
+          else
+            tokens = statement.tokens[1..-1]
+            tokval_list(tokens, :attr, :identifier, TkId).map do |value|
+              value.to_s
+            end
           end
         end
 
         def caller_method
           if statement.tokens.first.is_a?(TkIDENTIFIER)
             statement.tokens.first.text
+          elsif statement.tokens.first.is_a?(TkDEF)
+            extract_method_details.first
           else
             nil
           end
@@ -59,6 +63,24 @@ module YARD
 
         private
 
+        # Extracts method information for macro expansion only
+        #
+        # @todo This is a duplicate implementation of {MethodHandler}. Refactor.
+        # @return [Array<String,Array<Array<String>>>] the method name followed by method
+        #   arguments (name and optional value)
+        def extract_method_details
+          if statement.tokens.to_s =~ /^def\s+(#{METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
+            meth, args = $1, $2
+            meth.gsub!(/\s+/,'')
+            args = tokval_list(Parser::Ruby::Legacy::TokenList.new(args), :all)
+            args.map! {|a| k, v = *a.split('=', 2); [k.strip, (v ? v.strip : nil)] } if args
+            if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
+              meth = $`
+            end
+            return meth, args
+          end
+        end
+
         # 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

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

@@ -0,0 +1,9 @@
+# (see Ruby::CommentHandler)
+class YARD::Handlers::Ruby::Legacy::CommentHandler < YARD::Handlers::Ruby::Legacy::Base
+  handles TkCOMMENT
+  namespace_only
+
+  process do
+    register_docstring(nil)
+  end
+end

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

@@ -0,0 +1,16 @@
+module YARD
+  module Handlers
+    module Ruby
+      module Legacy
+        # (see Ruby::DSLHandler)
+        class DSLHandler < Base
+          include CodeObjects
+          include DSLHandlerMethods
+          handles TkIDENTIFIER
+          namespace_only
+          process { handle_comments }
+        end
+      end
+    end
+  end
+end

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

@@ -26,8 +26,6 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
 
     nobj = P(namespace, nobj.value) while nobj.type == :constant
     obj = register MethodObject.new(nobj, meth, mscope) do |o|
-      o.visibility = visibility
-      o.source = statement
       o.explicit = true
       o.parameters = args
     end

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

@@ -5,7 +5,7 @@ class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy:
 
   process do
     errors = []
-    statement.tokens[1..-1].to_s.split(/\s*,\s*/).each do |mixin|
+    statement.tokens[1..-1].to_s.split(/\s*,\s*/).reverse.each do |mixin|
       mixin = mixin.strip
       begin
         process_mixin(mixin)

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

@@ -0,0 +1,18 @@
+# (see Ruby::ModuleFunctionHandler)
+class YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler < YARD::Handlers::Ruby::Legacy::Base
+  handles /\A(module_function)(\s|\(|$)/
+  namespace_only
+
+  process do
+    if statement.tokens.size == 1
+      self.scope = :module
+    else
+      tokval_list(statement.tokens[2..-1], :attr).each do |name|
+        instance_method = MethodObject.new(namespace, name)
+        class_method = MethodObject.new(namespace, name, :module)
+        instance_method.copy_to(class_method)
+        class_method.visibility = :public
+      end
+    end
+  end
+end

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

@@ -3,28 +3,22 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
   handles :def, :defs
 
   process do
+    meth = statement.method_name(true).to_s
+    args = format_args
+    blk = statement.block
     nobj = namespace
     mscope = scope
     if statement.type == :defs
       if statement[0][0].type == :ident
         raise YARD::Parser::UndocumentableError, 'method defined on object instance'
       end
-      meth = statement[2][0]
       nobj = P(namespace, statement[0].source) if statement[0][0].type == :const
-      args = format_args(statement[3])
-      blk = statement[4]
       mscope = :class
-    else
-      meth = statement[0][0]
-      args = format_args(statement[1])
-      blk = statement[2]
     end
 
     nobj = P(namespace, nobj.value) while nobj.type == :constant
     obj = register MethodObject.new(nobj, meth, mscope) do |o|
-      o.visibility = visibility
-      o.source = statement.source
-      o.signature = method_signature(meth)
+      o.signature = method_signature
       o.explicit = true
       o.parameters = args
     end
@@ -75,8 +69,8 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
     parse_block(blk, :owner => obj) # mainly for yield/exceptions
   end
 
-  def format_args(args)
-    args = args.jump(:params)
+  def format_args
+    args = statement.parameters
     params = []
     params += args.required_params.map {|a| [a.source, nil] } if args.required_params
     params += args.optional_params.map {|a| [a[0].source, a[1].source] } if args.optional_params
@@ -86,9 +80,10 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
     params
   end
 
-  def method_signature(method_name)
-    if statement[1]
-      "def #{method_name}(#{statement[1].jump(:params).source})"
+  def method_signature
+    method_name = statement.method_name(true)
+    if statement.parameters.any? {|e| e }
+      "def #{method_name}(#{statement.parameters.source})"
     else
       "def #{method_name}"
     end

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

@@ -5,7 +5,7 @@ class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
 
   process do
     errors = []
-    statement.parameters(false).each do |mixin|
+    statement.parameters(false).reverse.each do |mixin|
       begin
         process_mixin(mixin)
       rescue YARD::Parser::UndocumentableError => err

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

@@ -0,0 +1,26 @@
+# Handles module_function calls to turn methods into public class methods.
+# Also creates a private instance copy of the method.
+class YARD::Handlers::Ruby::ModuleFunctionHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:module_function)
+  namespace_only
+
+  process do
+    return if (ident = statement.jump(:ident)) == statement
+    case statement.type
+    when :var_ref, :vcall
+      self.scope = :module
+    when :fcall, :command
+      statement[1].traverse do |node|
+        case node.type
+        when :symbol; name = node.first.source
+        when :string_content; name = node.source
+        else next
+        end
+        instance_method = MethodObject.new(namespace, name)
+        class_method = MethodObject.new(namespace, name, :module)
+        instance_method.copy_to(class_method)
+        class_method.visibility = :public
+      end
+    end
+  end
+end