yard 0.6.8 → 0.7.0

data/lib/yard/docstring.rb

@@ -1,45 +1,45 @@
 module YARD
-  # A documentation string, or "docstring" for short, encapsulates the 
+  # 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} 
+  #
+  # 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
-    
+
     # @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_reader :all
-    
+
     # @return [Boolean] whether the docstring was started with "##"
     attr_reader :hash_flag
     def hash_flag=(v) @hash_flag = v == nil ? false : v end
 
     # Matches a tag at the start of a comment line
     META_MATCH = /^@([a-z_0-9]+)(?:\s+(.*))?$/i
-    
+
     # @group Creating a Docstring Object
 
     # 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
@@ -48,12 +48,12 @@ module YARD
       @object = object
       @summary = nil
       @hash_flag = false
-      
+
       self.all = content
     end
-    
+
     # Adds another {Docstring}, copying over tags.
-    # 
+    #
     # @param [Docstring, String] other the other docstring (or string) to
     #   add.
     # @return [Docstring] a new docstring with both docstrings combines
@@ -65,23 +65,41 @@ module YARD
         super
       end
     end
-    
+
     # Replaces the docstring with new raw content. Called by {#all=}.
     # @param [String] content the raw comments to be parsed
     def replace(content)
+      content = content.join("\n") if content.is_a?(Array)
       @tags, @ref_tags = [], []
       @all = content
       super parse_comments(content)
     end
     alias all= replace
+    
+    # Deep-copies a docstring
+    # 
+    # @note This method creates a new docstring with new tag lists, but does
+    #   not create new individual tags. Modifying the tag objects will still
+    #   affect the original tags.
+    # @return [Docstring] a new copied docstring
+    # @since 0.7.0
+    def dup
+      obj = super
+      %w(all summary tags ref_tags).each do |name|
+        val = instance_variable_get("@#{name}")
+        obj.instance_variable_set("@#{name}", val ? val.dup : nil)
+      end
+      obj
+    end
 
     # @endgroup
-    
-    # @return [Fixnum] the first line of the {#line_range}.
+
+    # @return [Fixnum] the first line of the {#line_range}
+    # @return [nil] if there is no associated {#line_range}
     def line
-      line_range.first
+      line_range ? line_range.first : nil
     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
@@ -106,11 +124,64 @@ module YARD
       @summary += '.' unless @summary.empty?
       @summary
     end
+    
+    # Reformats and returns a raw representation of the tag data using the
+    # current tag and docstring data, not the original text.
+    # 
+    # @return [String] the updated raw formatted docstring data
+    # @since 0.7.0
+    # @todo Add Tags::Tag#to_raw and refactor
+    def to_raw
+      tag_data = tags.sort_by {|t| t.tag_name }.map do |tag|
+        case tag
+        when Tags::OverloadTag
+          tag_text = "@#{tag.tag_name} #{tag.signature}\n"
+          unless tag.docstring.blank?
+            tag_text += "\n" + tag.docstring.all.gsub(/\r?\n/, "\n  ")
+          end
+        else
+          tag_text = '@' + tag.tag_name
+          tag_text += ' [' + tag.types.join(', ') + ']' if tag.types
+          tag_text += ' ' + tag.name.to_s if tag.name
+          tag_text += "\n " if tag.name && tag.text
+          tag_text += ' ' + tag.text.strip.gsub(/\n/, "\n  ") if tag.text
+        end
+        tag_text
+      end
+      [strip, tag_data.join("\n")].reject {|l| l.empty? }.compact.join("\n")
+    end
 
     # @group Creating and Accessing Meta-data
-    
-    # Adds a tag or reftag object to the tag list
+
+    # Creates a tag from the {Tags::DefaultFactory tag factory}.
+    # 
+    # To add an already created tag object, use {#add_tag}
+    #
+    # @param [String] tag_name the tag name
+    # @param [String] tag_buf the text attached to the tag with newlines removed.
+    # @return [Tags::Tag, Tags::RefTag] a tag
+    def create_tag(tag_name, tag_buf)
+      if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
+        return create_ref_tag(tag_name, $1, $2)
+      end
+
+      tag_factory = Tags::Library.instance
+      tag_method = "#{tag_name}_tag"
+      if tag_name && tag_factory.respond_to?(tag_method)
+        add_tag(*[tag_factory.send(tag_method, tag_buf)].flatten)
+      else
+        log.warn "Unknown tag @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
+      end
+    rescue Tags::TagFormatError
+      log.warn "Invalid tag format for @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
+    end
+
+    # Adds a tag or reftag object to the tag list. If you want to parse
+    # tag data based on the {Tags::DefaultFactory} tag factory, use {#create_tag}
+    # instead.
+    # 
     # @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
+    # @return [void]
     def add_tag(*tags)
       tags.each_with_index do |tag, i|
         case tag
@@ -124,7 +195,7 @@ module YARD
         end
       end
     end
-    
+
     # Convenience method to return the first tag
     # object in the list of tag objects of that name
     #
@@ -155,6 +226,24 @@ module YARD
     def has_tag?(name)
       tags.any? {|tag| tag.tag_name.to_s == name.to_s }
     end
+    
+    # Delete all tags with +name+
+    # @param [String] name the tag name
+    # @return [void]
+    # @since 0.7.0
+    def delete_tags(name)
+      delete_tag_if {|tag| tag.tag_name.to_s == name.to_s }
+    end
+    
+    # Deletes all tags where the block returns true
+    # @yieldparam [Tags::Tag] tag the tag that is being tested
+    # @yieldreturn [Boolean] true if the tag should be deleted 
+    # @return [void]
+    # @since 0.7.0
+    def delete_tag_if(&block)
+      @tags.delete_if(&block)
+      @ref_tags.delete_if(&block)
+    end
 
     # Returns true if the docstring has no content that is visible to a template.
     #
@@ -168,51 +257,30 @@ module YARD
         empty? && @tags.empty? && @ref_tags.empty?
       end
     end
-    
+
     # @endgroup
 
     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 {Tags::RefTag}
     def create_ref_tag(tag_name, name, object_name)
       @ref_tags << Tags::RefTagList.new(tag_name, P(object, object_name), name)
     end
-    
-    # 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.
-    # @return [Tags::Tag, Tags::RefTag] a tag
-    def create_tag(tag_name, tag_buf)
-      if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
-        return create_ref_tag(tag_name, $1, $2)
-      end
-        
-      tag_factory = Tags::Library.instance
-      tag_method = "#{tag_name}_tag"
-      if tag_name && tag_factory.respond_to?(tag_method)
-        add_tag(*[tag_factory.send(tag_method, tag_buf)].flatten)
-      else
-        log.warn "Unknown tag @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
-      end
-    rescue Tags::TagFormatError
-      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 
+    # @param [String] comments
     #   the newline delimited array of comments. If the comments
-    #   are passed as a String, they will be split by newlines. 
-    # 
+    #   are passed as a String, they will be split by newlines.
+    #
     # @return [String] the non-metadata portion of the comments to
     #   be used as a docstring
     def parse_comments(comments)
@@ -226,11 +294,11 @@ module YARD
       tag_name, tag_klass, tag_buf = nil, nil, []
 
       (comments+['']).each_with_index do |line, index|
-        indent = line[/^\s*/].length 
+        indent = line[/^\s*/].length
         empty = (line =~ /^\s*$/ ? true : false)
         done = comments.size == index
 
-        if tag_name && (((indent < orig_indent && !empty) || done || 
+        if tag_name && (((indent < orig_indent && !empty) || done ||
             (indent == 0 && !empty)) || (indent <= last_indent && line =~ META_MATCH))
           create_tag(tag_name, tag_buf.join("\n"))
           tag_name, tag_buf, = nil, []
@@ -244,12 +312,12 @@ module YARD
           orig_indent = indent if orig_indent == 0
           # Extra data added to the tag on the next line
           last_empty = last_line =~ /^[ \t]*$/ ? true : false
-          
+
           tag_buf << '' if last_empty
           tag_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
         elsif !tag_name
           # Regular docstring text
-          docstring << line << "\n" 
+          docstring << line << "\n"
         end
 
         last_indent = indent

data/lib/yard/globals.rb

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

data/lib/yard/handlers/base.rb

@@ -7,12 +7,12 @@ module YARD
       # The object the error occurred on
       # @return [CodeObjects::Base] a code object
       attr_accessor :object
-      
+
       def initialize(object) @object = object end
     end
-    
-    # Handlers are pluggable semantic parsers for YARD's code generation 
-    # phase. They allow developers to control what information gets 
+
+    # Handlers are pluggable semantic parsers for YARD's code generation
+    # phase. They allow developers to control what information gets
     # generated by YARD, giving them the ability to, for instance, document
     # any Ruby DSLs that a customized framework may use. A good example
     # of this would be the ability to document and generate meta data for
@@ -21,45 +21,45 @@ module YARD
     # takes advantage of class level declarations could add these to the
     # documentation in a very explicit format by treating them as first-
     # class objects in any outputted documentation.
-    # 
-    # == Overview of a Typical Handler Scenario 
-    # 
+    #
+    # == Overview of a Typical Handler Scenario
+    #
     # Generally, a handler class will declare a set of statements which
     # it will handle using the {handles} class declaration. It will then
     # implement the {#process} method to do the work. The processing would
-    # usually involve the manipulation of the {#namespace}, {#owner} 
-    # {CodeObjects::Base code objects} or the creation of new ones, in 
-    # which case they should be registered by {#register}, a method that 
+    # usually involve the manipulation of the {#namespace}, {#owner}
+    # {CodeObjects::Base code objects} or the creation of new ones, in
+    # which case they should be registered by {#register}, a method that
     # sets some basic attributes for the new objects.
-    # 
+    #
     # Handlers are usually simple and take up to a page of code to process
     # and register a new object or add new attributes to the current +namespace+.
-    # 
-    # == Setting up a Handler for Use 
-    # 
+    #
+    # == Setting up a Handler for Use
+    #
     # A Handler is automatically registered when it is subclassed from the
     # base class. The only other thing that needs to be done is to specify
     # which statement the handler will process. This is done with the +handles+
     # declaration, taking either a {Parser::Ruby::Legacy::RubyToken}, {String} or `Regexp`.
     # Here is a simple example which processes module statements.
-    # 
+    #
     #   class MyModuleHandler < YARD::Handlers::Base
     #     handles TkMODULE
-    # 
+    #
     #     def process
     #       # do something
     #     end
     #   end
-    # 
-    # == Processing Handler Data 
-    # 
-    # The goal of a specific handler is really up to the developer, and as 
+    #
+    # == Processing Handler Data
+    #
+    # The goal of a specific handler is really up to the developer, and as
     # such there is no real guideline on how to process the data. However,
     # it is important to know where the data is coming from to be able to use
     # it.
-    # 
-    # === +statement+ Attribute 
-    # 
+    #
+    # === +statement+ Attribute
+    #
     # The +statement+ attribute pertains to the {Parser::Ruby::Legacy::Statement} object
     # containing a set of tokens parsed in by the parser. This is the main set
     # of data to be analyzed and processed. The comments attached to the statement
@@ -67,71 +67,71 @@ module YARD
     # the data to be processed will live in the +tokens+ attribute. This list
     # can be converted to a +String+ using +#to_s+ to parse the data with
     # regular expressions (or other text processing mechanisms), if needed.
-    # 
-    # === +namespace+ Attribute 
-    # 
-    # The +namespace+ attribute is a {CodeObjects::NamespaceObject namespace object} 
+    #
+    # === +namespace+ Attribute
+    #
+    # The +namespace+ attribute is a {CodeObjects::NamespaceObject namespace object}
     # which represents the current namespace that the parser is in. For instance:
-    # 
+    #
     #   module SomeModule
     #     class MyClass
     #       def mymethod; end
     #     end
     #   end
-    # 
+    #
     # If a handler was to parse the 'class MyClass' statement, it would
     # be necessary to know that it belonged inside the SomeModule module.
     # This is the value that +namespace+ would return when processing such
     # a statement. If the class was then entered and another handler was
     # called on the method, the +namespace+ would be set to the 'MyClass'
     # code object.
-    # 
-    # === +owner+ Attribute 
-    # 
+    #
+    # === +owner+ Attribute
+    #
     # The +owner+ attribute is similar to the +namespace+ attribute in that
     # it also follows the scope of the code during parsing. However, a namespace
     # object is loosely defined as a module or class and YARD has the ability
     # to parse beyond module and class blocks (inside methods, for instance),
-    # so the +owner+ attribute would not be limited to modules and classes. 
-    # 
+    # so the +owner+ attribute would not be limited to modules and classes.
+    #
     # To put this into context, the example from above will be used. If a method
     # handler was added to the mix and decided to parse inside the method body,
     # the +owner+ would be set to the method object but the namespace would remain
     # set to the class. This would allow the developer to process any method
     # definitions set inside a method (def x; def y; 2 end end) by adding them
     # to the correct namespace (the class, not the method).
-    # 
+    #
     # In summary, the distinction between +namespace+ and +owner+ can be thought
     # of as the difference between first-class Ruby objects (namespaces) and
     # second-class Ruby objects (methods).
-    # 
-    # === +visibility+ and +scope+ Attributes 
-    # 
+    #
+    # === +visibility+ and +scope+ Attributes
+    #
     # Mainly needed for parsing methods, the +visibility+ and +scope+ attributes
     # refer to the public/protected/private and class/instance values (respectively)
     # of the current parsing position.
-    # 
-    # == Parsing Blocks in Statements 
-    # 
+    #
+    # == Parsing Blocks in Statements
+    #
     # In addition to parsing a statement and creating new objects, some
     # handlers may wish to continue parsing the code inside the statement's
     # block (if there is one). In this context, a block means the inside
     # of any statement, be it class definition, module definition, if
-    # statement or classic 'Ruby block'. 
-    # 
-    # For example, a class statement would be "class MyClass" and the block 
-    # would be a list of statements including the method definitions inside 
-    # the class. For a class handler, the programmer would execute the 
-    # {#parse_block} method to continue parsing code inside the block, with 
-    # the +namespace+ now pointing to the class object the handler created. 
-    # 
-    # YARD has the ability to continue into any block: class, module, method, 
-    # even if statements. For this reason, the block parsing method must be 
+    # statement or classic 'Ruby block'.
+    #
+    # For example, a class statement would be "class MyClass" and the block
+    # would be a list of statements including the method definitions inside
+    # the class. For a class handler, the programmer would execute the
+    # {#parse_block} method to continue parsing code inside the block, with
+    # the +namespace+ now pointing to the class object the handler created.
+    #
+    # YARD has the ability to continue into any block: class, module, method,
+    # 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
@@ -139,20 +139,20 @@ module YARD
     # @see #owner
     # @see #register
     # @see #parse_block
-    class Base 
-      # For accessing convenience, eg. "MethodObject" 
+    class Base
+      # For accessing convenience, eg. "MethodObject"
       # instead of the full qualified namespace
       include YARD::CodeObjects
-      
+
       include Parser
-      
+
       class << self
         # Clear all registered subclasses. Testing purposes only
-        # @return [void] 
+        # @return [void]
         def clear_subclasses
           @@subclasses = []
         end
-        
+
         # Returns all registered handler subclasses.
         # @return [Array<Base>] a list of handlers
         def subclasses
@@ -165,70 +165,70 @@ module YARD
         end
 
         # Declares the statement type which will be processed
-        # by this handler. 
-        # 
+        # by this handler.
+        #
         # A match need not be unique to a handler. Multiple
         # handlers can process the same statement. However,
         # in this case, care should be taken to make sure that
         # {#parse_block} would only be executed by one of
         # the handlers, otherwise the same code will be parsed
         # multiple times and slow YARD down.
-        # 
+        #
         # @param [Parser::RubyToken, Symbol, String, Regexp] matches
         #   statements that match the declaration will be
-        #   processed by this handler. A {String} match is 
-        #   equivalent to a +/\Astring/+ regular expression 
-        #   (match from the beginning of the line), and all 
+        #   processed by this handler. A {String} match is
+        #   equivalent to a +/\Astring/+ regular expression
+        #   (match from the beginning of the line), and all
         #   token matches match only the first token of the
         #   statement.
-        # 
+        #
         def handles(*matches)
           (@handlers ||= []).push(*matches)
         end
-        
+
         # This class is implemented by {Ruby::Base} and {Ruby::Legacy::Base}.
         # To implement a base handler class for another language, implement
         # this method to return true if the handler should process the given
         # statement object. Use {handlers} to enumerate the matchers declared
         # for the handler class.
-        # 
+        #
         # @param statement a statement object or node (depends on language type)
         # @return [Boolean] whether or not this handler object should process
         #   the given statement
         def handles?(statement)
           raise NotImplementedError, "override #handles? in a subclass"
         end
-        
+
         # @return [Array] a list of matchers for the handler object.
         # @see handles?
         def handlers
           @handlers ||= []
         end
-        
+
         # Declares that the handler should only be called when inside a
         # {CodeObjects::NamespaceObject}, not a method body.
-        # 
+        #
         # @return [void]
         def namespace_only
           @namespace_only = true
         end
-        
+
         # @return [Boolean] whether the handler should only be processed inside
         #   a namespace.
         def namespace_only?
           (@namespace_only ||= false) ? true : false
         end
-        
+
         # Declares that a handler should only be called when inside a filename
         # by its basename or a regex match for the full path.
-        # 
+        #
         # @param [String, Regexp] filename a matching filename or regex
         # @return [void]
         # @since 0.6.2
         def in_file(filename)
           (@in_files ||= []) << filename
         end
-        
+
         # @return [Boolean] whether the filename matches the declared file
         #   match for a handler. If no file match is specified, returns true.
         # @since 0.6.2
@@ -245,12 +245,16 @@ module YARD
             end
           end
         end
-        
+
         # Generates a +process+ method, equivalent to +def process; ... end+.
         # Blocks defined with this syntax will be wrapped inside an anonymous
         # module so that the handler class can be extended with mixins that
         # override the +process+ method without alias chaining.
-        # 
+        #
+        # @macro yard.handlers.process
+        #   @method process
+        #   Main processing callback
+        #   @return [void]
         # @see #process
         # @return [void]
         # @since 0.5.4
@@ -268,57 +272,63 @@ module YARD
 
       # The main handler method called by the parser on a statement
       # that matches the {handles} declaration.
-      # 
+      #
       # Subclasses should override this method to provide the handling
-      # functionality for the class. 
-      # 
+      # functionality for the class.
+      #
       # @return [Array<CodeObjects::Base>, CodeObjects::Base, Object]
       #   If this method returns a code object (or a list of them),
       #   they are passed to the +#register+ method which adds basic
       #   attributes. It is not necessary to return any objects and in
       #   some cases you may want to explicitly avoid the returning of
       #   any objects for post-processing by the register method.
-      # 
+      #
       # @see handles
       # @see #register
-      # 
+      #
       def process
         raise NotImplementedError, "#{self} did not implement a #process method for handling."
       end
-      
+
       # Parses the semantic "block" contained in the statement node.
-      # 
+      #
       # @abstract Subclasses should call {Processor#process parser.process}
       def parse_block(*args)
         raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
       end
-      
+
       protected
-      
-      # @return [Processor] the processor object that manages all global state 
+
+      # @return [Processor] the processor object that manages all global state
       #   during handling.
       attr_reader :parser
-      
+
       # @return [Object] the statement object currently being processed. Usually
       #   refers to one semantic language statement, though the strict definition
       #   depends on the parser used.
       attr_reader :statement
-      
+
       # (see Processor#owner)
       attr_accessor :owner
-      
+
       # (see Processor#namespace)
       attr_accessor :namespace
-      
+
       # (see Processor#visibility)
       attr_accessor :visibility
-      
+
       # (see Processor#scope)
       attr_accessor :scope
+
+      # (see Processor#globals)
+      attr_reader :globals
+
+      # (see Processor#extra_state)
+      attr_reader :extra_state
       
       undef owner, owner=, namespace, namespace=
       undef visibility, visibility=, scope, scope=
-      
+
       def owner; parser.owner end
       def owner=(v) parser.owner=(v) end
       def namespace; parser.namespace end
@@ -327,17 +337,19 @@ module YARD
       def visibility=(v); parser.visibility=(v) end
       def scope; parser.scope end
       def scope=(v); parser.scope=(v) end
-      
+      def globals; parser.globals end
+      def extra_state; parser.extra_state end
+
       # Executes a given block with specific state values for {#owner},
       # {#namespace} and {#scope}.
-      # 
+      #
       # @param [Proc] block the block to execute with specific state
-      # @option opts [CodeObjects::NamespaceObject] :namespace (value of #namespace) 
+      # @option opts [CodeObjects::NamespaceObject] :namespace (value of #namespace)
       #   the namespace object that {#namespace} will be equal to for the
-      #   duration of the block. 
-      # @option opts [Symbol] :scope (:instance) 
+      #   duration of the block.
+      # @option opts [Symbol] :scope (:instance)
       #   the scope for the duration of the block.
-      # @option opts [CodeObjects::Base] :owner (value of #owner) 
+      # @option opts [CodeObjects::Base] :owner (value of #owner)
       #   the owner object (method) for the duration of the block
       # @yield a block to execute with the given state values.
       def push_state(opts = {}, &block)
@@ -360,43 +372,52 @@ module YARD
         self.scope = sc
         self.owner = oo
       end
-      
-      # Do some post processing on a list of code objects. 
-      # Adds basic attributes to the list of objects like 
+
+      # Do some post processing on a list of code objects.
+      # Adds basic attributes to the list of objects like
       # the filename, line number, {CodeObjects::Base#dynamic},
       # source code and {CodeObjects::Base#docstring},
       # but only if they don't exist.
-      # 
+      #
       # @param [Array<CodeObjects::Base>] objects
       #   the list of objects to post-process.
-      # 
+      #
       # @return [CodeObjects::Base, Array<CodeObjects::Base>]
       #   returns whatever is passed in, for chainability.
-      # 
+      #
       def register(*objects)
         objects.flatten.each do |object|
           next unless object.is_a?(CodeObjects::Base)
-          
+
           begin
             ensure_loaded!(object.namespace)
             object.namespace.children << object
           rescue NamespaceMissingError
           end
-          
+
           # Yield the object to the calling block because ruby will parse the syntax
-          #   
+          #
           #     register obj = ClassObject.new {|o| ... }
-          # 
+          #
           # as the block for #register. We need to make sure this gets to the object.
-          yield(object) if block_given? 
-          
+          yield(object) if block_given?
+
           object.add_file(parser.file, statement.line, statement.comments)
 
           # Add docstring if there is one.
-          object.docstring = statement.comments if statement.comments
-          object.docstring.hash_flag = statement.comments_hash_flag
-          object.docstring.line_range = statement.comments_range
-          
+          if statement.comments
+            object.docstring = Docstring.new(statement.comments, object)
+          end
+
+          # Expand/create any @macro tags
+          expand_macro(object, find_or_create_macro(object))
+
+          # Add hash_flag/line_range
+          if statement.comments
+            object.docstring.hash_flag = statement.comments_hash_flag
+            object.docstring.line_range = statement.comments_range
+          end
+
           # Add group information
           if statement.group
             unless object.namespace.is_a?(Proxy)
@@ -404,7 +425,7 @@ module YARD
             end
             object.group = statement.group
           end
-          
+
           # Add transitive tags
           Tags::Library.transitive_tags.each do |tag|
             next if object.namespace.is_a?(Proxy)
@@ -412,12 +433,12 @@ module YARD
             next if object.has_tag?(tag)
             object.docstring.add_tag(*object.namespace.tags(tag))
           end
-          
+
           # Add source only to non-class non-module objects
           unless object.is_a?(NamespaceObject)
             object.source ||= statement
           end
-          
+
           # Make it dynamic if its owner is not its namespace.
           # This generally means it was defined in a method (or block of some sort)
           object.dynamic = true if owner != namespace
@@ -428,17 +449,17 @@ module YARD
       # Ensures that a specific +object+ has been parsed and loaded into the
       # registry. This is necessary when adding data to a namespace, for instance,
       # since the namespace may not have been processed yet (it can be located
-      # in a file that has not been handled). 
-      # 
-      # Calling this method defers the handler until all other files have been 
+      # in a file that has not been handled).
+      #
+      # Calling this method defers the handler until all other files have been
       # processed. If the object gets resolved, the rest of the handler continues,
       # otherwise an exception is raised.
-      # 
+      #
       # @example Adding a mixin to the String class programmatically
       #   ensure_loaded! P('String')
       #   # "String" is now guaranteed to be loaded
       #   P('String').mixins << P('MyMixin')
-      # 
+      #
       # @param [Proxy, CodeObjects::Base] object the object to resolve.
       # @param [Integer] max_retries the number of times to defer the handler
       #   before raising a +NamespaceMissingError+.
@@ -455,7 +476,7 @@ module YARD
             nil
           end
         end
-        
+
         unless CONTINUATIONS_SUPPORTED
           unless $NO_CONTINUATION_WARNING
             $NO_CONTINUATION_WARNING = true
@@ -464,11 +485,11 @@ module YARD
           end
           raise NamespaceMissingError, object
         end
-        
+
         retries = 0
         context = callcc {|c| c }
-        retries += 1 
-        
+        retries += 1
+
         if object.is_a?(Proxy)
           if retries <= max_retries
             log.debug "Missing object #{object} in file `#{parser.file}', moving it to the back of the line."
@@ -479,6 +500,74 @@ module YARD
         end
         object
       end
+      
+      # @group Macro Support
+      
+      # @abstract Implement this method to return the parameters in a method call
+      #   statement. It should return an empty list if the statement is not a
+      #   method call.
+      # @return [Array<String>] a list of argument names
+      def call_params
+        raise NotImplementedError
+      end
+      
+      # @abstract Implement this method to return the method being called in
+      #   a method call. It should return nil if the statement is not a method
+      #   call.
+      # @return [String] the method name being called
+      # @return [nil] if the statement is not a method call
+      def caller_method
+        raise NotImplementedError
+      end
+      
+      # Attempts to find or create a macro if a +@macro+ tag is found in the
+      # docstring (or the object's docstring).
+      # 
+      # @param [Docstring, CodeObjects::Base] object_or_docstring the docstring
+      #   or it's object with which to check for a macro
+      # @return [CodeObjects::MacroObject] the newly created macro
+      # @return [nil] if the docstring does not create or reference a macro
+      def find_or_create_macro(object_or_docstring)
+        if object_or_docstring.is_a?(Docstring)
+          object, docstring = nil, object_or_docstring
+        else
+          object, docstring = object_or_docstring, object_or_docstring.docstring
+        end
+        return unless macro_tag = docstring.tag(:macro)
+        unless macro_tag.name
+          if object
+            log.warn "Invalid/missing macro name for #{object.path} (#{parser.file}:#{statement.line})"
+            return nil
+          else
+            raise UndocumentableError, 'method/attribute, missing macro name'
+          end
+        end
+        caller_obj = caller_method ? P(namespace, caller_method) : nil
+        if macro = MacroObject.find_or_create(docstring, caller_obj)
+          attached_method_name = caller_method
+          if object && object.is_a?(MethodObject) && object.scope == :class
+            macro.method_object = object
+            attached_method_name = object.name.to_s
+          end
+          if macro.attached?
+            globals.__attached_macros ||= {}
+            globals.__attached_macros[attached_method_name] ||= []
+            globals.__attached_macros[attached_method_name] |= [macro]
+          end
+        end
+        macro
+      end
+      
+      # Sets the docstring on +object+ to the expanded macro.
+      # @param [CodeObjects::Base] object the object to expand the macro on
+      # @param [CodeObjects::MacroObject] macro the macro object to expand
+      # @return [void]
+      def expand_macro(object, macro)
+        return unless macro
+        all_params = ([caller_method] + call_params).compact
+        data = MacroObject.apply_macro(macro, object.docstring, all_params, statement.source)
+        object.docstring = Docstring.new(data, object)
+      end
     end
   end
 end