yard 0.5.8 → 0.6.0

data/lib/yard/handlers/processor.rb

@@ -12,16 +12,35 @@ module YARD
     # 
     # @see Handlers::Base
     class Processor
+
+      class << self
+        # Registeres a new namespace for handlers of the given type.
+        # @since 0.6.0
+        def register_handler_namespace(type, ns)
+          namespace_for_handler[type] = ns
+        end
+
+        # @return [Hash] a list of registered parser type extensions
+        # @private
+        # @since 0.6.0
+        attr_reader :namespace_for_handler
+        undef namespace_for_handler
+        def namespace_for_handler; @@parser_type_extensions ||= {} end
+      end
+
+      register_handler_namespace :ruby, Ruby
+      register_handler_namespace :ruby18, Ruby::Legacy
+
       # @return [String] the filename
       attr_accessor :file
 
       # @return [CodeObjects::NamespaceObject] the current namespace
       attr_accessor :namespace
       
-      # @return [Symbol] the current visibility
+      # @return [Symbol] the current visibility (public, private, protected)
       attr_accessor :visibility
       
-      # @return [Symbol] the current scope
+      # @return [Symbol] the current scope (class, instance)
       attr_accessor :scope
       
       # @return [CodeObjects::Base, nil] unlike the namespace, the owner
@@ -33,7 +52,7 @@ module YARD
       # @return [Boolean] whether or not {Parser::LoadOrderError} is raised
       attr_accessor :load_order_errors
       
-      # @return [Symbol] the parser type (:ruby, :ruby18 or :c)
+      # @return [Symbol] the parser type (:ruby, :ruby18, :c)
       attr_accessor :parser_type
       
       # Creates a new Processor for a +file+.
@@ -113,10 +132,7 @@ module YARD
       # @return [Module] the module containing the handlers depending on
       #   {#parser_type}.
       def handler_base_namespace
-        case parser_type
-        when :ruby;   Ruby
-        when :ruby18; Ruby::Legacy
-        end
+        self.class.namespace_for_handler[parser_type]
       end
       
       # Loads handlers from {#handler_base_namespace}. This ensures that

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

@@ -1,3 +1,4 @@
+# Handles alias and alias_method calls
 class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
   handles :alias, method_call(:alias_method)
   

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

@@ -1,3 +1,4 @@
+# Handles +attr_*+ statements in modules/classes
 class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
   handles method_call(:attr)
   handles method_call(:attr_reader)
@@ -45,6 +46,7 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
             o.source ||= full_src
             o.signature ||= src
             o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
+            o.visibility = visibility
           end
 
           # Register the objects explicitly
@@ -59,6 +61,12 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
   
   protected
   
+  # Strips out any non-essential arguments from the attr statement.
+  # 
+  # @param [Array<Parser::Ruby::AstNode>] params a list of the parameters
+  #   in the attr call.
+  # @return [Array<String>] the validated attribute names
+  # @raise [Parser::UndocumentableError] if the arguments are not valid.
   def validated_attribute_names(params)
     params.map do |obj|
       case obj.type

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

@@ -1,10 +1,33 @@
 module YARD
   module Handlers
     module Ruby
+      # To implement a custom handler matcher, subclass this class and implement
+      # {#matches?} to return whether a node matches the handler.
+      # 
+      # @example A Custom Handler Matcher Extension
+      #   # Implements a handler that checks for a specific string
+      #   # in the node's source.
+      #   class MyExtension < HandlesExtension
+      #     def matches?(node) node.source.include?(name) end
+      #   end
+      # 
+      #   # This handler will handle any node where the source includes 'foo'
+      #   class MyHandler < Handlers::Ruby::Base
+      #     handles MyExtension.new('foo') 
+      #   end
       class HandlesExtension
+        # Creates a new extension with a specific matcher value +name+
+        # @param [Object] name the matcher value to check against {#matches?}
         def initialize(name) @name = name end
+          
+        # Tests if the node matches the handler
+        # @param [Parser::Ruby::AstNode] node a Ruby node
+        # @return [Boolean] whether the +node+ matches the handler
         def matches?(node) raise NotImplementedError end
+          
         protected
+        
+        # @return [String] the extension matcher value
         attr_reader :name
       end
       
@@ -28,18 +51,62 @@ module YARD
         def matches?(node) !node.send(name).is_a?(FalseClass) end
       end
       
+      # This is the base handler class for the new-style (1.9) Ruby parser.
+      # All handlers that subclass this base class will be used when the 
+      # new-style parser is used. For implementing legacy handlers, see
+      # {Legacy::Base}.
+      # 
+      # @abstract See {Handlers::Base} for subclassing information.
+      # @see Handlers::Base
+      # @see Legacy::Base
       class Base < Handlers::Base
         class << self
           include Parser::Ruby
           
+          # @group Statement Matcher Extensions
+          
+          # Matcher for handling any type of method call. Method calls can
+          # be expressed by many {AstNode} types depending on the syntax
+          # with which it is called, so YARD allows you to use this matcher
+          # to simplify matching a method call.
+          # 
+          # @example Match the "describe" method call
+          #   handles method_call(:describe)
+          #   
+          #   # The following will be matched:
+          #   # describe(...)
+          #   # object.describe(...)
+          #   # describe "argument" do ... end
+          # 
+          # @param [#to_s] name matches the method call of this name
+          # @return [void]
           def method_call(name)
             MethodCallWrapper.new(name.to_s)
           end
           
-          def meta_type(meth)
-            TestNodeWrapper.new(meth.to_s + "?")
+          # Matcher for handling a node with a specific meta-type. An {AstNode}
+          # has a {AstNode#type} to define its type but can also be associated
+          # with a set of types. For instance, +:if+ and +:unless+ are both
+          # of the meta-type +:condition+.
+          # 
+          # A meta-type is any method on the {AstNode} class ending in "?", 
+          # though you should not include the "?" suffix in your declaration.
+          # Some examples are: "condition", "call", "literal", "kw", "token",
+          # "ref".
+          # 
+          # @example Handling any conditional statement (if, unless)
+          #   handles meta_type(:condition)
+          # @param [Symbol] type the meta-type to match. A meta-type can be
+          #   any method name + "?" that {AstNode} responds to.
+          # @return [void]
+          def meta_type(type)
+            TestNodeWrapper.new(type.to_s + "?")
           end
           
+          # @group Testing for a Handler
+          
+          # @return [Boolean] whether or not an {AstNode} object should be
+          #   handled by this handler
           def handles?(node)
             handlers.any? do |a_handler| 
               case a_handler 
@@ -60,6 +127,8 @@ module YARD
 
         include Parser::Ruby
         
+        # @group Parsing an Inner Block
+        
         def parse_block(inner_node, opts = {})
           push_state(opts) do
             nodes = inner_node.type == :list ? inner_node.children : [inner_node]

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

@@ -1,3 +1,13 @@
+# Matches if/unless conditions inside classes and attempts to process only
+# one branch (by evaluating the condition if possible).
+# 
+# @example A simple class conditional
+#   class Foo
+#     if 0
+#       # This method is ignored
+#       def xyz; end
+#     end
+#   end
 class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles meta_type(:condition)

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

@@ -1,3 +1,4 @@
+# Handles class declarations
 class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
   include YARD::Handlers::Ruby::StructHandlerMethods
   namespace_only
@@ -75,15 +76,17 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
   end
   
   def struct_superclass_name(superclass)
-    first = superclass.parameters.first
-    if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
-      return "Struct::#{first[0][0][0]}"
+    if superclass.call?
+      first = superclass.parameters.first
+      if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
+        return "Struct::#{first[0][0][0]}"
+      end
     end
     "Struct"
   end
   
   def parse_struct_superclass(klass, superclass)
-    return unless superclass.parameters
+    return unless superclass.call? && superclass.parameters
     members = extract_parameters(superclass)
     create_attributes(klass, members)
   end

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

@@ -1,3 +1,4 @@
+# Handles a class variable (@@variable)
 class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles :assign

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

@@ -1,3 +1,4 @@
+# Handles any constant assignment
 class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
   namespace_only
   handles :assign

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

@@ -1,3 +1,4 @@
+# Handles 'raise' calls inside methods
 class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
   handles method_call(:raise)
   

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

@@ -1,6 +1,5 @@
-# `extend` works just like `include` except that it always
-# mixes the module in in class scope,
-# and that it can handle `extend self`.
+# 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)

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

@@ -1,3 +1,4 @@
+# (see Ruby::AliasHandler)
 class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aalias(_method)?(\s|\()/
   

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

@@ -1,3 +1,4 @@
+# (see Ruby::AttributeHandler)
 class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aattr(?:_(?:reader|writer|accessor))?(?:\s|\()/
   
@@ -44,6 +45,7 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
             o.source ||= full_src
             o.signature ||= src
             o.docstring = statement.comments.to_s.empty? ? doc : statement.comments
+            o.visibility = visibility
           end
         
           # Register the objects explicitly

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

@@ -1,10 +1,16 @@
 module YARD
   module Handlers
     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)
           handlers.any? do |a_handler|
             case a_handler
@@ -20,6 +26,13 @@ module YARD
 
         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}
+        # 
+        # @param [Hash] opts State options
+        # @option opts (see Handlers::Base#push_state)
+        # @see Handlers::Base#push_state #push_state
         def parse_block(opts = {})
           push_state(opts) do
             if statement.block
@@ -32,8 +45,8 @@ module YARD
         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 
-        # "foo #{bar}" without any interpolation. The return value of the identifier
+        # 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:
         # 

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

@@ -1,3 +1,5 @@
+# (see Ruby::ClassConditionHandler)
+# @since 0.5.4
 class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby::Legacy::Base
   namespace_only
   handles TkIF, TkELSIF, TkUNLESS
@@ -22,6 +24,7 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
   # @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
     
@@ -60,10 +63,12 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
     condition
   end
   
+  # @since 0.5.5
   def parse_then_block
     parse_block
   end
   
+  # @since 0.5.5
   def parse_else_block
     stmtlist = YARD::Parser::Ruby::Legacy::StatementList
     stmtlist.new(statement.block).each do |stmt|

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

@@ -1,3 +1,4 @@
+# (see Ruby::ClassHandler)
 class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy::Base
   include YARD::Handlers::Ruby::StructHandlerMethods
   handles TkCLASS
@@ -73,10 +74,12 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
   end
   
   def struct_superclass_name(superclass)
-    paramstring = superclass.match(/\A(Struct)\.new\((.*?)\)/)[2].split(",")
-    first = paramstring.first.strip
-    if first[0,1] =~ /['"]/ && first[-1,1] =~ /['"]/ && first !~ /\#\{/
-      return "Struct::#{first[1..-2]}"
+    if match = superclass.match(/\A(Struct)\.new\((.*?)\)/)
+      paramstring = match[2].split(",")
+      first = paramstring.first.strip
+      if first[0,1] =~ /['"]/ && first[-1,1] =~ /['"]/ && first !~ /\#\{/
+        return "Struct::#{first[1..-2]}"
+      end
     end
     "Struct"
   end

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

@@ -1,3 +1,4 @@
+# (see Ruby::ClassVariableHandler)
 class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby::Legacy::Base
   HANDLER_MATCH = /\A@@\w+\s*=\s*/m
   handles HANDLER_MATCH

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

@@ -1,3 +1,4 @@
+# (see Ruby::ConstantHandler)
 class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Legacy::Base
   HANDLER_MATCH = /\A[A-Z]\w*\s*=[^=]\s*/m
   handles HANDLER_MATCH

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

@@ -1,3 +1,4 @@
+# (see Ruby::ExceptionHandler)
 class YARD::Handlers::Ruby::Legacy::ExceptionHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Araise(\s|\()/
   

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

@@ -1,6 +1,4 @@
-# `extend` works just like `include` except that it always
-# mixes the module in in class scope,
-# and that it can handle `extend self`.
+# (see Ruby::ExtendHandler)
 class YARD::Handlers::Ruby::Legacy::ExtendHandler < YARD::Handlers::Ruby::Legacy::MixinHandler
   handles /\Aextend(\s|\()/
 

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

@@ -1,3 +1,4 @@
+# (see Ruby::MethodHandler)
 class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkDEF
     
@@ -13,11 +14,14 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
     else
       raise YARD::Parser::UndocumentableError, "method: invalid name"
     end
-    
+
     # Class method if prefixed by self(::|.) or Module(::|.)
     if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
-      mscope, meth = :class, $1
-      nobj = P(namespace, $`) unless $` == "self"
+      mscope, meth, prefix = :class, $1, $`
+      if prefix =~ /^[a-z]/ && prefix != "self"
+        raise YARD::Parser::UndocumentableError, 'method defined on object instance'
+      end
+      nobj = P(namespace, prefix) unless prefix == "self"
     end
     
     obj = register MethodObject.new(nobj, meth, mscope) do |o| 

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

@@ -1,3 +1,4 @@
+# (see Ruby::MixinHandler)
 class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Ainclude(\s|\()/
   
@@ -23,6 +24,6 @@ class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy:
       obj = Proxy.new(namespace, obj.value)
     end
 
-    namespace.mixins(scope) << obj
+    namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)
   end
 end