yard 0.6.8 → 0.7.0

data/lib/yard/handlers/processor.rb

@@ -1,15 +1,20 @@
+require 'ostruct'
+
 module YARD
   module Handlers
-    # Iterates over all statements in a file and delegates them to the 
+    # 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", 
+    # 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.
-    # 
+    # where objects are being created from. You can also access extra stateful
+    # properties that any handler can set during the duration of the post
+    # processing of a file from {#extra_state}. If you need to access state
+    # across different files, look at {#globals}.
+    #
     # @see Handlers::Base
     class Processor
 
@@ -36,37 +41,68 @@ module YARD
 
       # @return [CodeObjects::NamespaceObject] the current namespace
       attr_accessor :namespace
-      
+
       # @return [Symbol] the current visibility (public, private, protected)
       attr_accessor :visibility
-      
+
       # @return [Symbol] the current scope (class, instance)
       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, :c)
       attr_accessor :parser_type
       
-      # Creates a new Processor for a +file+.
+      # Handlers can share state for the entire post processing stage through 
+      # this attribute. Note that post processing stage spans multiple files.
+      # To share state only within a single file, use {#extra_state}
       # 
+      # @example Sharing state among two handlers
+      #   class Handler1 < YARD::Handlers::Ruby::Base
+      #     handles :class
+      #     process { globals.foo = :bar }
+      #   end
+      # 
+      #   class Handler2 < YARD::Handlers::Ruby::Base
+      #     handles :method
+      #     process { puts globals.foo }
+      #   end
+      # @return [OpenStruct] global shared state for post-processing stage
+      # @see #extra_state
+      attr_accessor :globals
+      
+      # Share state across different handlers inside of a file.
+      # This attribute is similar to {#visibility}, {#scope}, {#namespace}
+      # and {#owner}, in that they all maintain state across all handlers
+      # for the entire source file. Use this attribute to store any data
+      # your handler might need to save during the parsing of a file. If
+      # you need to save state across files, see {#globals}.
+      # 
+      # @return [OpenStruct] an open structure that can store arbitrary data
+      # @see #globals
+      attr_accessor :extra_state
+
+      # 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. 
+      #   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 
+      #   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)
+      # @param [OpenStruct] globals the object holding all state during the
+      #   post processing stage
+      def initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type, globals = nil)
         @file = file || "(stdin)"
         @namespace = YARD::Registry.root
         @visibility = :public
@@ -75,26 +111,28 @@ module YARD
         @load_order_errors = load_order_errors
         @parser_type = parser_type
         @handlers_loaded = {}
+        @globals = globals || OpenStruct.new
+        @extra_state = OpenStruct.new
         load_handlers
       end
-      
+
       # Processes a list of statements by finding handlers to process each
       # one.
-      # 
+      #
       # @param [Array] statements a list of statements
-      # @return [void] 
+      # @return [void]
       def process(statements)
         statements.each_with_index do |stmt, index|
-          find_handlers(stmt).each do |handler| 
+          find_handlers(stmt).each do |handler|
             begin
               handler.new(self, stmt).process
             rescue Parser::LoadOrderError => loaderr
               raise # Pass this up
             rescue NamespaceMissingError => missingerr
-              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized." 
-              log.warn "If this class/method is part of your source tree, this will affect your documentation results." 
+              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized."
+              log.warn "If this class/method is part of your source tree, this will affect your documentation results."
               log.warn "You can correct this issue by loading the source file for this object before `#{file}'"
-              log.warn 
+              log.warn
             rescue Parser::UndocumentableError => undocerr
               log.warn "in #{handler.to_s}: Undocumentable #{undocerr.message}"
               log.warn "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
@@ -106,9 +144,9 @@ module YARD
           end
         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)
@@ -118,9 +156,9 @@ module YARD
           handler.matches_file?(file) && handler.handles?(statement)
         end
       end
-      
+
       private
-      
+
       # Returns the handler base class
       # @return [Base] the base class
       def handler_base_class
@@ -128,13 +166,13 @@ module YARD
       end
 
       # The module holding the handlers to be loaded
-      # 
+      #
       # @return [Module] the module containing the handlers depending on
       #   {#parser_type}.
       def handler_base_namespace
         self.class.namespace_for_handler[parser_type]
       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

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

@@ -1,7 +1,8 @@
 # Handles alias and alias_method calls
 class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
   handles :alias, method_call(:alias_method)
-  
+  namespace_only
+
   process do
     names = []
     if statement.type == :alias
@@ -17,7 +18,7 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
       end
     end
     raise YARD::Parser::UndocumentableError, "alias/alias_method" 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|
@@ -30,11 +31,13 @@ class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
       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/attribute_handler.rb

@@ -4,12 +4,13 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
   handles method_call(:attr_reader)
   handles method_call(:attr_writer)
   handles method_call(:attr_accessor)
-  
+  namespace_only
+
   process do
     return if statement.type == :var_ref
     read, write = true, false
     params = statement.parameters(false).dup
-    
+
     # Change read/write based on attr_reader/writer/accessor
     case statement.method_name(true)
     when :attr
@@ -28,7 +29,7 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
     # Add all attributes
     validated_attribute_names(params).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)
@@ -58,11 +59,11 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
       end
     end
   end
-  
+
   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

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

@@ -3,97 +3,97 @@ module YARD
     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') 
+      #     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
-      
+
       class MethodCallWrapper < HandlesExtension
         def matches?(node)
           case node.type
           when :var_ref
             if !node.parent || node.parent.type == :list
-              return true if node[0].type == :ident && node[0][0] == name
+              return true if node[0].type == :ident && (name.nil? || node[0][0] == name)
             end
           when :fcall, :command
-            return true if node[0][0] == name
+            return true if name.nil? || node[0][0] == name
           when :call, :command_call
-            return true if node[2][0] == name
+            return true if name.nil? || node[2][0] == name
           end
           false
         end
       end
-      
+
       class TestNodeWrapper < HandlesExtension
         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 
+      # 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)
+          def method_call(name = nil)
+            MethodCallWrapper.new(name ? name.to_s : nil)
           end
-          
+
           # 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 "?", 
+          #
+          # 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
@@ -102,14 +102,14 @@ module YARD
           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 
+            handlers.any? do |a_handler|
+              case a_handler
               when Symbol
                 a_handler == node.type
               when String
@@ -126,15 +126,34 @@ module YARD
         end
 
         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]
             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
+        end
+
+        def caller_method
+          if statement.call?
+            statement.method_name(true).to_s
+          elsif statement.type == :var_ref
+            statement[0].jump(:ident).source
+          else
+            nil
+          end
+        end
       end
     end
   end

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

@@ -1,6 +1,6 @@
 # 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
@@ -9,9 +9,9 @@
 #     end
 #   end
 class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
-  namespace_only
   handles meta_type(:condition)
-  
+  namespace_only
+
   process do
     condition = parse_condition
     if condition == nil
@@ -24,24 +24,24 @@ class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
       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)
   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.condition.type
@@ -66,18 +66,18 @@ class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
         condition = false
       end
     end
-    
+
     # Invert an unless condition
     if statement.type == :unless || statement.type == :unless_mod
       condition = !condition if condition != nil
     end
     condition
   end
-  
+
   def parse_then_block
     parse_block(statement.then_block)
   end
-  
+
   def parse_else_block
     parse_block(statement.else_block) if statement.else_block
   end