yard 0.7.5 → 0.8.0

data/lib/yard/server/commands/list_command.rb

@@ -5,44 +5,20 @@ module YARD
       class ListCommand < LibraryCommand
         include Templates::Helpers::BaseHelper
 
-        def items; raise NotImplementedError end
-        def type; raise NotImplementedError end
-
         def run
-          options.update(:items => items, :template => :doc_server,
-                         :list_type => request.path.split('/').last, :type => :full_list)
-          render
-        end
-      end
-
-      # Returns the list of classes / modules in a library
-      class ListClassesCommand < ListCommand
-        def type; :class end
-
-        def items
           Registry.load_all
-          run_verifier(Registry.all(:class, :module))
+          options.update(:objects => run_verifier(Registry.all(:class, :module)))
+          list_type = request.path.split('/').last
+          meth = "generate_#{list_type}_list"
+          tpl = fulldoc_template
+          if tpl.respond_to?(meth)
+            tpl.send(meth)
+            cache(tpl.contents)
+          else
+            not_found
+          end
         end
       end
-
-      # Returns the list of methods in a library
-      class ListMethodsCommand < ListCommand
-        include Templates::Helpers::ModuleHelper
-
-        def type; :methods end
-
-        def items
-          Registry.load_all
-          items = Registry.all(:method).sort_by {|m| m.name.to_s }
-          prune_method_listing(items)
-        end
-      end
-
-      # Returns the list of README/extra files in a library
-      class ListFilesCommand < ListCommand
-        def type; :files end
-        def items; options[:files] end
-      end
     end
   end
 end

data/lib/yard/server/commands/search_command.rb

@@ -6,6 +6,7 @@ module YARD
       class SearchCommand < LibraryCommand
         include Templates::Helpers::BaseHelper
         include Templates::Helpers::ModuleHelper
+        include DocServerHelper
 
         attr_accessor :results, :query
 
@@ -14,7 +15,7 @@ module YARD
           self.query = request.query['q']
           redirect("/#{adapter.router.docs_prefix}/#{single_library ? library : ''}") if query.nil? || query =~ /\A\s*\Z/
           if found = Registry.at(query)
-            redirect(serializer.serialized_path(found))
+            redirect(url_for(found))
           end
           search_for_object
           request.xhr? ? serve_xhr : serve_normal
@@ -26,13 +27,18 @@ module YARD
 
         private
 
+        def url_for(object)
+          File.join('', base_path(router.docs_prefix),
+            serializer.serialized_path(object))
+        end
+
         def serve_xhr
           self.headers['Content-Type'] = 'text/plain'
           self.body = visible_results.map {|o|
             [(o.type == :method ? o.name(true) : o.name).to_s,
              o.path,
              o.namespace.root? ? '' : o.namespace.path,
-             serializer.serialized_path(o)
+             url_for(o)
             ].join(",")
           }.join("\n")
         end

data/lib/yard/server/doc_server_helper.rb

@@ -9,9 +9,11 @@ module YARD
       # @return (see Templates::Helpers::HtmlHelper#url_for)
       def url_for(obj, anchor = nil, relative = false)
         return '' if obj.nil?
+        return url_for_index if obj == '_index.html'
         return "/#{obj}" if String === obj
         File.join('', base_path(router.docs_prefix), super(obj, anchor, false))
       end
+
       # Modifies {Templates::Helpers::HtmlHelper#url_for_file} to return a URL instead
       # of a disk location.
       # @param (see Templates::Helpers::HtmlHelper#url_for_file)
@@ -24,6 +26,38 @@ module YARD
           (anchor ? "##{anchor}" : "")
       end
 
+      # Modifies {Templates::Helpers::HtmlHelper#url_for_list} to return a URL
+      # based on the list prefix instead of a HTML filename.
+      # @param (see Templates::Helpers::HtmlHelper#url_for_list)
+      # @return (see Templates::Helpers::HtmlHelper#url_for_list)
+      def url_for_list(type)
+        File.join('', base_path(router.list_prefix), type.to_s)
+      end
+
+      # Returns the frames URL for the page
+      # @return (see Templates::Helpers::HtmlHelper#url_for_frameset)
+      def url_for_frameset
+        url = options.file ? url_for_file(options.file) : url_for(object)
+        url = url.gsub(%r{^/#{base_path(router.docs_prefix)}/}, '')
+        File.join('', base_path(router.docs_prefix), "frames", url)
+      end
+
+      # Returns the main URL, first checking a readme and then linking to the index
+      # @return (see Templates::Helpers::HtmlHelper#url_for_main)
+      def url_for_main
+        if options.frames && !options.command.path.empty?
+          File.join('', base_path(router.docs_prefix), options.command.path)
+        else
+          options.readme ? url_for_file(options.readme) : url_for_index
+        end
+      end
+
+      # Returns the URL for the alphabetic index page
+      # @return (see Templates::Helpers::HtmlHelper#url_for_index)
+      def url_for_index
+        File.join('', base_path(router.docs_prefix), 'index')
+      end
+
       # @example The base path for a library 'foo'
       #   base_path('docs') # => 'docs/foo'
       # @param [String] path the path prefix for a base path URI

data/lib/yard/server/rack_adapter.rb

@@ -44,11 +44,15 @@ module YARD
       include WEBrick::HTTPUtils
 
       # Responds to Rack requests and builds a response with the {Router}.
-      # @return [Array(Number,Hash,Array)] the Rack-style response
+      # @return [Array(Numeric,Hash,Array)] the Rack-style response
       def call(env)
         request = Rack::Request.new(env)
         request.path_info = unescape(request.path_info) # unescape things like %3F
         router.call(request)
+      rescue StandardError => ex
+        log.backtrace(ex)
+        [500, {'Content-Type' => 'text/plain'},
+          [ex.message + "\n" + ex.backtrace.join("\n")]]
       end
 
       # Starts the +Rack::Server+. This method will pass control to the server and

data/lib/yard/server/router.rb

@@ -48,7 +48,7 @@ module YARD
       # file through {Commands::StaticFileCommand} if no route is found.
       #
       # @param [Adapter Dependent] request the request object
-      # @return [Array(Number,Hash,Array)] the Rack-style server response data
+      # @return [Array(Numeric,Hash,Array)] the Rack-style server response data
       def call(request)
         self.request = request
         if result = (check_static_cache || route)
@@ -97,8 +97,8 @@ module YARD
       #
       # @return [Array(Numeric,Hash,Array<String>)] the Rack-style response
       # @return [nil] if no route is matched
-      def route
-        path = request.path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
+      def route(path = request.path)
+        path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
         return route_index if path.empty? || path == docs_prefix
         case path
         when /^(#{docs_prefix}|#{list_prefix}|#{search_prefix})(\/.*|$)/
@@ -150,13 +150,7 @@ module YARD
       # @return (see #route_docs)
       def route_list(library, paths)
         return if paths.empty?
-        case paths.shift
-        when "class";   cmd = ListClassesCommand
-        when "methods"; cmd = ListMethodsCommand
-        when "files";   cmd = ListFilesCommand
-        else; return
-        end
-        cmd.new(final_options(library, paths)).call(request)
+        ListCommand.new(final_options(library, paths)).call(request)
       end
 
       # Routes requests from {#search_prefix} and calls the appropriate command

data/lib/yard/server/static_caching.rb

@@ -27,7 +27,7 @@ module YARD
       #   end
       #
       #   class YARD::Server::Router; include MemoryCaching; end
-      # @return [Array(Number,Hash,Array)] the Rack-style response
+      # @return [Array(Numeric,Hash,Array)] the Rack-style response
       # @return [nil] if no cache is available and routing should continue
       # @see Commands::Base#cache
       def check_static_cache
@@ -42,4 +42,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/server/templates/default/fulldoc/html/css/custom.css

@@ -49,11 +49,11 @@ form.search input { margin-left: 5px; width: 250px; border: 1px solid #99f; -moz
 	font-size: 12px;
 	line-height: 16px;
 	overflow: hidden;
-	
+
 }
 
 .ac_loading {
-	background: white url('/images/loading.gif') right center no-repeat;
+	background: white url('/images/processing.gif') right center no-repeat;
 }
 
 .ac_even {

data/lib/yard/server/templates/default/fulldoc/html/js/live.js

@@ -1,17 +1,3 @@
-function searchFrameLinks() {
-  $('#method_list_link').unbind("click").click(function() {
-    toggleSearchFrame(this, '/' + library + '/methods');
-  });
-
-  $('#class_list_link').unbind("click").click(function() {
-    toggleSearchFrame(this, '/' + library + '/class');
-  });
-
-  $('#file_list_link').unbind("click").click(function() {
-    toggleSearchFrame(this, '/' + library + '/files');
-  });
-}
-
 function methodPermalinks() {
   if ($($('#content h1')[0]).text().match(/^Method:/)) return;
 
@@ -28,5 +14,4 @@ function methodPermalinks() {
   });
 }
 
-$(searchFrameLinks);
 $(methodPermalinks);

data/lib/yard/server/templates/default/layout/html/breadcrumb.erb

@@ -3,7 +3,7 @@
 </form>
 <script type="text/javascript" charset="utf-8">
   $(function() {
-    $('#search_box').autocomplete('/<%= base_path(router.search_prefix) %>', {
+    $('#search_box').autocomplete($('#search_box').parent().attr('action'), {
       width: document.body.className == 'frames' ? 250 : 340,
       formatItem: function(item) {
         var values = item[0].split(",");
@@ -31,13 +31,13 @@
   <% end %>
   <% if object.is_a?(CodeObjects::Base) && @file.nil? %>
     <% unless @single_library %>&raquo;<% end %>
-    <a href="/<%= base_path(router.docs_prefix) %>"><% if object.root? || object.type == :method %>Index<% else %>Index (<%= object.name.to_s[0] %>)<% end %></a> &raquo;
+    <a href="<%= url_for_index %>"><% if object.root? || object.type == :method %>Index<% else %>Index (<%= object.name.to_s[0] %>)<% end %></a> &raquo;
     <%= @breadcrumb.map {|obj| "<span class='title'>" + linkify(obj, obj.name) + "</span>" }.join(" &raquo; ") %>
     <%= @breadcrumb.size > 0 ? " &raquo; " : "" %>
     <span class='title'><%= object.root? ? "Top Level Namespace" : object.name(true) %></span>
   <% else %>
     <% if (@breadcrumb_title || object != '_index.html') && !@single_library %>&raquo; <% end %>
-    <% if object != '_index.html' %><a href="/<%= base_path(router.docs_prefix) %>">Index</a> &raquo; <% end %>
+    <% if object != '_index.html' %><a href="<%= url_for_index %>">Index</a> &raquo; <% end %>
     <span class='title'><%= @breadcrumb_title %></span>
   <% end %>
 

data/lib/yard/server/templates/default/layout/html/script_setup.erb

@@ -0,0 +1,8 @@
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '/';
+  docsPrefix = '<%= base_path(router.docs_prefix) %>';
+  listPrefix = '<%= base_path(router.list_prefix) %>';
+  searchPrefix = '<%= base_path(router.search_prefix) %>';
+  framesUrl = '<%= url_for_frameset %>';
+</script>

data/lib/yard/server/templates/doc_server/processing/html/processing.erb

@@ -8,7 +8,7 @@
     <script type="text/javascript" charset="utf-8" src="/js/jquery.js"></script>
     <script type="text/javascript" charset="utf-8">
       function checkPage(process) {
-        $.ajax({cache: false, url: "<%= @path %>" + (process ? "?process=true" : ""), statusCode: { 200: function() { window.location = "<%= @path %>"; } } });
+        $.ajax({cache: false, url: "<%= router.request.path %>" + (process ? "?process=true" : ""), statusCode: { 200: function() { window.location = "<%= @path %>"; } } });
         setTimeout('checkPage()', 2000);
       }
       function setFade() {

data/lib/yard/server/templates/doc_server/search/html/setup.rb

@@ -3,6 +3,6 @@ def init
 end
 
 def search
-  options[:breadcrumb_title] = h("Search for '#{@query}'")
+  options.breadcrumb_title = h("Search for '#{@query}'")
   yieldall :contents => erb(:search)
 end

data/lib/yard/tags/default_factory.rb

@@ -47,6 +47,24 @@ module YARD
         Tag.new(tag_name, text, types, name)
       end
 
+      # Parses tag text and creates a new tag with formally declared types, a title
+      # on the first line and descriptive text
+      #
+      # @param tag_name        the name of the tag to parse
+      # @param [String] text   the raw tag text
+      # @return [Tag]          a tag object with the tag_name, name, types and text values filled
+      def parse_tag_with_types_and_title(tag_name, text)
+        name, types, text = *extract_types_and_name_from_text_unstripped(text)
+        if name
+          title, desc = name, text
+        else
+          title, desc = *extract_title_and_desc_from_text(text)
+        end
+        Tag.new(tag_name, desc, types, title)
+      rescue TagFormatError
+        Tag.new(tag_name, '', types, nil)
+      end
+
       def parse_tag_with_title_and_text(tag_name, text)
         title, desc = *extract_title_and_desc_from_text(text)
         Tag.new(tag_name, desc, nil, title)
@@ -105,6 +123,15 @@ module YARD
       #   list (or nil), followed by the type list parsed into an array of
       #   strings, followed by the text following the type list.
       def extract_types_and_name_from_text(text, opening_types = TYPELIST_OPENING_CHARS, closing_types = TYPELIST_CLOSING_CHARS)
+        before, list, text = *extract_types_and_name_from_text_unstripped(text, opening_types, closing_types)
+        if list.nil?
+          [nil, nil, text.strip]
+        else
+          [before ? before.strip : nil, list.map {|e| e.strip }, text.strip]
+        end
+      end
+
+      def extract_types_and_name_from_text_unstripped(text, opening_types = TYPELIST_OPENING_CHARS, closing_types = TYPELIST_CLOSING_CHARS)
         s, e = 0, 0
         before = ''
         list, level, seen_space = [''], 0, false
@@ -114,7 +141,7 @@ module YARD
             s = i if level == 0
             level += 1
           elsif closing_types.include?(c)
-            level -= 1 unless list.last[-1,1] == '='
+            level -= 1 unless list.last[-1,1] == '=' && c == '>'
             break e = i if level == 0
             list.last << c
           elsif c == ',' && level == 1
@@ -129,11 +156,11 @@ module YARD
           end
         end
 
-        before = before.empty? ? nil : before.strip
+        before = before.empty? ? nil : before
         if list.size == 1 && list.first == ''
-          [nil, nil, text.strip]
+          [nil, nil, text]
         else
-          [before, list.map {|x| x.strip }, text[(e+1)..-1].strip]
+          [before, list, text[(e+1)..-1]]
         end
       end
     end

data/lib/yard/tags/directives.rb

@@ -0,0 +1,593 @@
+require 'ostruct'
+
+module YARD
+  module Tags
+    # The base directive class. Subclass this class to create a custom
+    # directive, registering it with {Library.define_directive}. Directive
+    # classes are executed via the {#call} method, which perform all directive
+    # processing on the object.
+    #
+    # If processing occurs within a handler, the {#handler} attribute is
+    # available to access more information about parsing context and state.
+    # Handlers are only available when parsing from {Parser::SourceParser},
+    # not when parsing directly from {DocstringParser}. If the docstring is
+    # attached to an object declaration, {#object} will be set and available
+    # to modify the generated code object directly. Note that both of these
+    # attributes may be nil, and directives should test their existence
+    # before attempting to use them.
+    #
+    # @abstract Subclasses should implement {#call}.
+    # @see Library.define_directive
+    # @since 0.8.0
+    class Directive
+      # @return [Tag] the meta-data tag containing data input to the directive
+      attr_accessor :tag
+
+      # Set this field to replace the directive definition inside of a docstring
+      # with arbitrary text. For instance, the {MacroDirective} uses this field
+      # to expand its macro data in place of the call to a +@!macro+.
+      #
+      # @return [String] the text to expand in the original docstring in place
+      #   of this directive definition.
+      # @return [nil] if no expansion should take place for this directive
+      attr_accessor :expanded_text
+
+      # @return [DocstringParser] the parser that is parsing all tag
+      #   information out of the docstring
+      attr_accessor :parser
+
+      # @!attribute [r] object
+      # @return [CodeObjects::Base, nil] the object the parent docstring is
+      #   attached to. May be nil.
+      def object; parser.object end
+
+      # @!attribute [r] handler
+      # @return [Handlers::Base, nil] the handler object the docstring parser
+      #   might be attached to. May be nil. Only available when parsing
+      #   through {Parser::SourceParser}.
+      def handler; parser.handler end
+
+      # @!endgroup
+
+      # @param [Tag] tag the meta-data tag containing all input to the docstring
+      # @param [DocstringParser] parser the docstring parser object
+      def initialize(tag, parser)
+        self.tag = tag
+        self.parser = parser
+        self.expanded_text = nil
+      end
+
+      # @!group Parser callbacks
+
+      # Called when processing the directive. Subclasses should implement
+      # this method to perform all functionality of the directive.
+      #
+      # @abstract implement this method to perform all data processing for
+      #   the directive.
+      # @return [void]
+      def call; raise NotImplementedError end
+
+      # Called after parsing all directives and tags in the docstring. Used
+      # to perform any cleanup after all directives perform their main task.
+      # @return [void]
+      def after_parse; end
+
+      protected :parser
+    end
+
+    # Ends a group listing definition. Group definition automatically end
+    # when class or module blocks are closed, and defining a new group overrides
+    # the last group definition, but occasionally you need to end the current
+    # group to return to the default listing. Use {tag:!group} to begin a
+    # group listing.
+    #
+    # @example
+    #   class Controller
+    #     # @!group Callbacks
+    #
+    #     def before_filter; end
+    #     def after_filter; end
+    #
+    #     # @!endgroup
+    #
+    #     def index; end
+    #   end
+    # @see tag:!group
+    # @since 0.6.0
+    class EndGroupDirective < Directive
+      def call
+        return unless handler
+        handler.extra_state.group = nil
+      end
+    end
+
+    # Defines a group listing. All methods (and attributes) seen after this
+    # directive are placed into a group with the given description as the
+    # group name. The group listing is used by templates to organize methods
+    # and attributes into respective logical groups. To end a group listing
+    # use {tag:!endgroup}.
+    #
+    # @note A group definition only applies to the scope it is defined in.
+    #   If a new class or module is opened after the directive, this directive
+    #   will not apply to methods in that class or module.
+    # @example
+    #   # @!group Callbacks
+    #
+    #   def before_filter; end
+    #   def after_filter; end
+    # @see tag:!endgroup
+    # @since 0.6.0
+    class GroupDirective < Directive
+      def call
+        return unless handler
+        handler.extra_state.group = tag.text
+      end
+    end
+
+    # Defines a block of text to be expanded whenever the macro is called by name
+    # in subsequent docstrings. The macro data can be any arbitrary text data, be
+    # it regular documentation, meta-data tags or directives.
+    #
+    # == Defining a Macro
+    #
+    # A macro must first be defined in order to be used. Note that a macro is also
+    # expanded upon definition if it defined on an object (the docstring of a
+    # method, class, module or constant object as opposed to a free standing
+    # comment). To define a macro, use the "new" or "attach" identifier in the
+    # types specifier list. A macro will also automatically be created if an
+    # indented macro data block is given, so the keywords are not strictly needed.
+    #
+    # === Anonymous Macros
+    #
+    # In addition to standard named macros, macros can be defined anonymously if
+    # no name is given. In this case, they can not be re-used in future docstrings,
+    # but they will expand in the first definition. This is useful when needing
+    # to take advantage of the macro expansion variables (described below).
+    #
+    # == Using a Macro
+    #
+    # To re-use a macro in another docstring after it is defined, simply use
+    # <tt>@!macro the_name</tt> with no indented block of macro data. The resulting
+    # data will be expanded in place.
+    #
+    # == Attaching a Macro to a DSL Method
+    #
+    # Macros can be defined to auto-expand on DSL-style class method calls. To
+    # define a macro to be auto expanded in this way, use the "attach" keyword
+    # in the type specifier list ("new" is implied).
+    #
+    # Attached macros can also be attached directly on the class method declaration
+    # that provides the DSL method to its subclasses. The syntax in either case
+    # is the same.
+    #
+    # == Macro Expansion Variables
+    #
+    # In the case of using macros on DSL-style method calls, a number of expansion
+    # variables can be used for interpolation inside of the macro data. The variables,
+    # similar in syntax to Ruby's global variables, are as follows:
+    #
+    # * $0 - the method name being called
+    # * $1, $2, $3, ... - the Nth argument in the method call
+    # * $& - the full source line
+    #
+    # The following example shows what the expansion variables might hold for a given
+    # DSL method call:
+    #
+    #   property :foo, :a, :b, :c, String
+    #   # $0 => "property"
+    #   # $1 => "foo"
+    #   # $2 => "a"
+    #   # $& => "property :foo, :a, :b, :c, String"
+    #
+    # === Ranges
+    #
+    # Ranges are also acceptable with the syntax <tt>${N-M}</tt>. Negative values
+    # on either N or M are valid, and refer to indexes from the end of the list.
+    # Consider a DSL method that creates a method using the first argument with
+    # argument names following, ending with the return type of the method. This
+    # could be documented as:
+    #
+    #     # @!macro dsl_method
+    #     #   @!method $1(${2--2})
+    #     #   @return [${-1}] the return value of $0
+    #     create_method_with_args :foo, :a, :b, :c, String
+    #
+    # As described, the method is using the signature <tt>foo(a, b, c)</tt> and the return
+    # type from the last argument, +String+. When using ranges, tokens are joined
+    # with commas. Note that this includes using $0:
+    #
+    #     !!!plain
+    #     $0-1 # => Interpolates to "create_method_with_args, foo"
+    #
+    # If you want to separate them with spaces, use <tt>$1 $2 $3 $4 ...</tt>. Note that
+    # if the token cannot be expanded, it will return the empty string (not an error),
+    # so it would be safe to list <tt>$1 $2 ... $10</tt>, for example.
+    #
+    # === Escaping Interpolation
+    #
+    # Interpolation can be escaped by prefixing the +$+ with +\+, like so:
+    #
+    #     # @!macro foo
+    #     #   I have \$2.00 USD.
+    #
+    # @example Defining a simple macro
+    #   # @!macro [new] returnself
+    #   #   @return [self] returns itself
+    # @example Using a simple macro in multiple docstrings
+    #   # Documentation for map
+    #   # ...
+    #   # @macro returnself
+    #   def map; end
+    #
+    #   # Documentation for filter
+    #   # ...
+    #   # @macro returnself
+    #   def filter; end
+    # @example Attaching a macro to a class method (for DSL usage)
+    #     class Resource
+    #       # Defines a new property
+    #       # @param [String] name the property name
+    #       # @param [Class] type the property's type
+    #       # @!macro [attach] property
+    #       #   @return [$2] the $1 property
+    #       def self.property(name, type) end
+    #     end
+    #
+    #     class Post < Resource
+    #       property :title, String
+    #       property :view_count, Integer
+    #     end
+    # @example Attaching a macro directly to a DSL method
+    #     class Post < Resource
+    #       # @!macro [attach] property
+    #       #   @return [$2] the $1 property
+    #       property :title, String
+    #
+    #       # Macro will expand on this definition too
+    #       property :view_count, Integer
+    #     end
+    # @since 0.7.0
+    class MacroDirective < Directive
+      def call
+        raise TagFormatError if tag.name.nil? && tag.text.to_s.empty?
+        unless macro_data = find_or_create
+          warn
+          return
+        end
+
+        self.expanded_text = expand(macro_data)
+      end
+
+      private
+
+      def new?
+        (tag.types && tag.types.include?('new')) ||
+          (tag.text && !tag.text.strip.empty?)
+      end
+
+      def attach?
+         class_method? || # always attach to class methods
+          (tag.types && tag.types.include?('attach'))
+      end
+
+      def class_method?
+        object && object.is_a?(CodeObjects::MethodObject) &&
+          object.scope == :class
+      end
+
+      def anonymous?
+        tag.name.nil? || tag.name.empty?
+      end
+
+      def expand(macro_data)
+        return if attach? && class_method?
+        return if !anonymous? && new? &&
+          (!handler || handler.statement.source.empty?)
+        call_params = []
+        caller_method = nil
+        full_source = ''
+        if handler
+          call_params = handler.call_params
+          caller_method = handler.caller_method
+          full_source = handler.statement.source
+        end
+        all_params = ([caller_method] + call_params).compact
+        CodeObjects::MacroObject.expand(macro_data, all_params, full_source)
+      end
+
+      def find_or_create
+        if new? || attach?
+          if handler && attach?
+            obj = object ? object :
+              P("#{handler.namespace}.#{handler.caller_method}")
+          else
+            obj = nil
+          end
+          if anonymous? # anonymous macro
+            return tag.text || ""
+          else
+            macro = CodeObjects::MacroObject.create(tag.name, tag.text, obj)
+          end
+        else
+          macro = CodeObjects::MacroObject.find(tag.name)
+        end
+
+        macro ? macro.macro_data : nil
+      end
+
+      def warn
+        if object && handler
+          log.warn "Invalid/missing macro name for " +
+            "#{object.path} (#{handler.parser.file}:#{handler.statement.line})"
+        end
+      end
+    end
+
+    # Defines a method object with a given method signature, using indented
+    # block data as the method's docstring. The signature is similar to the
+    # {tag:overload} tag. The comment containing this directive does not need
+    # to be attached to any source, but if it is, that source code will be
+    # used as the method's source.
+    #
+    # To define an attribute method, see {tag:!attribute}
+    #
+    # @note For backwards compatibility support, you do not need to indent
+    #   the method's docstring text. If a +@!method+ directive is seen with
+    #   no indented block, the entire docstring is used as the new method's
+    #   docstring text.
+    # @example Defining a simple method
+    #   # @!method quit(username, message = "Quit")
+    #   #   Sends a quit message to the server for a +username+.
+    #   #   @param [String] username the username to quit
+    #   #   @param [String] message the quit message
+    #   quit_message_method
+    # @example Attaching multiple methods to the same source
+    #   # @!method method1
+    #   # @!method method2
+    #   create_methods :method1, :method2
+    # @see tag:!attribute
+    # @since 0.7.0
+    class MethodDirective < Directive
+      SCOPE_MATCH = /\A\s*self\s*\.\s*/
+
+      def call; end
+
+      def after_parse
+        return unless handler
+        use_indented_text
+        create_object
+      end
+
+      protected
+
+      def method_name
+        sig = sanitized_tag_signature
+        if sig && sig =~ /^#{CodeObjects::METHODNAMEMATCH}(\s|\(|$)/
+          sig[/\A\s*([^\(; \t]+)/, 1]
+        else
+          handler.call_params.first
+        end
+      end
+
+      def method_signature
+        "def #{sanitized_tag_signature || method_name}"
+      end
+
+      def sanitized_tag_signature
+        if tag.name && tag.name =~ SCOPE_MATCH
+          parser.state.scope = :class
+          $'
+        else
+          tag.name
+        end
+      end
+
+      def use_indented_text
+        return if tag.text.empty?
+        handler = parser.handler
+        object = parser.object
+        self.parser = DocstringParser.new(parser.library)
+        parser.parse(tag.text, object, handler)
+      end
+
+      def create_object
+        name = method_name
+        scope = parser.state.scope || handler.scope
+        visibility = parser.state.visibility || handler.visibility
+        ns = CodeObjects::NamespaceObject === object ? object : handler.namespace
+        obj = CodeObjects::MethodObject.new(ns, name, scope)
+        handler.register_file_info(obj)
+        handler.register_source(obj)
+        handler.register_visibility(obj, visibility)
+        handler.register_group(obj)
+        obj.signature = method_signature
+        obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
+          parser.raw_text)
+        handler.register_module_function(obj)
+        obj
+      end
+    end
+
+    # Defines an attribute with a given name, using indented block data as the
+    # attribute's docstring. If the type specifier is supplied with "r", "w", or
+    # "rw", the attribute is made readonly, writeonly or readwrite respectively.
+    # A readwrite attribute is the default, if no type is specified. The comment
+    # containing this directive does not need to be attached to any source, but
+    # if it is, that source code will be used as the method's source.
+    #
+    # To define an regular method, see {tag:!method}
+    #
+    # @note For backwards compatibility support, you do not need to indent
+    #   the attribute's docstring text. If an +@!attribute+ directive is seen with
+    #   no indented block, the entire docstring is used as the new attribute's
+    #   docstring text.
+    # @example Defining a simple readonly attribute
+    #   # @!attribute [r] count
+    #   #   @return [Fixnum] the size of the list
+    # @example Defining a simple readwrite attribute
+    #   # @!attribute name
+    #   #   @return [String] the name of the user
+    # @see tag:!method
+    # @since 0.7.0
+    class AttributeDirective < MethodDirective
+      def after_parse
+        return unless handler
+        use_indented_text
+        create_attribute_data(create_object)
+      end
+
+      protected
+
+      def method_name
+        name = sanitized_tag_signature || handler.call_params.first
+        name += '=' unless readable?
+        name
+      end
+
+      def method_signature
+        if readable?
+          "def #{method_name}"
+        else
+          "def #{method_name}(value)"
+        end
+      end
+
+      private
+
+      def create_attribute_data(object)
+        return unless object
+        clean_name = object.name.to_s.sub(/=$/, '')
+        attrs = object.namespace.attributes[object.scope]
+        attrs[clean_name] ||= SymbolHash[:read => nil, :write => nil]
+        if readable?
+          attrs[clean_name][:read] = object
+        end
+        if writable?
+          if object.name.to_s[-1,1] == '='
+            writer = object
+            writer.parameters = [['value', nil]]
+          else
+            writer = CodeObjects::MethodObject.new(object.namespace,
+              object.name.to_s + '=', object.scope)
+            writer.signature = "def #{object.name}=(value)"
+            writer.visibility = object.visibility
+            writer.dynamic = object.dynamic
+            writer.source = object.source
+            writer.group = object.group
+            writer.parameters = [['value', nil]]
+            handler.register_file_info(writer)
+          end
+          attrs[clean_name][:write] = writer
+        end
+      end
+
+      def writable?
+        !tag.types || tag.types.join.include?('w')
+      end
+
+      def readable?
+        !tag.types || tag.types.join =~ /(?!w)r/
+      end
+    end
+
+    # Parses a block of code as if it were present in the source file at that
+    # location. This directive is useful if a class has dynamic meta-programmed
+    # behaviour that cannot be recognized by YARD.
+    #
+    # You can specify the language of the code block using the types
+    # specification list. By default, the code language is "ruby".
+    #
+    # @example Documenting dynamic module inclusion
+    #   class User
+    #     # includes "UserMixin" and extends "UserMixin::ClassMethods"
+    #     # using the UserMixin.included callback.
+    #     # @!parse include UserMixin
+    #     # @!parse extend UserMixin::ClassMethods
+    #   end
+    # @example Declaring a method as an attribute
+    #   # This should really be an attribute
+    #   # @!parse attr_reader :foo
+    #   def object; @parent.object end
+    # @example Parsing C code
+    #   # @!parse [c]
+    #   #   void Init_Foo() {
+    #   #     rb_define_method(rb_cFoo, "method", method, 0);
+    #   #   }
+    # @since 0.8.0
+    class ParseDirective < Directive
+      def call
+        lang = tag.types ? tag.types.first.to_sym :
+          (handler ? handler.parser.parser_type : :ruby)
+        if handler && lang == handler.parser.parser_type
+          pclass = Parser::SourceParser.parser_types[handler.parser.parser_type]
+          pobj = pclass.new(tag.text, handler.parser.file)
+          pobj.parse
+          handler.parser.process(pobj.enumerator)
+        else # initialize a new parse chain
+          src_parser = Parser::SourceParser.new(lang, handler ? handler.globals : nil)
+          src_parser.file = handler.parser.file if handler
+          src_parser.parse(StringIO.new(tag.text))
+        end
+      end
+    end
+
+    # Modifies the current parsing scope (class or instance). If this
+    # directive is defined on a docstring attached to an object definition,
+    # it is applied only to that object. Otherwise, it applies the scope
+    # to all future objects in the namespace.
+    #
+    # @example Modifying the scope of a DSL method
+    #   # @!scope class
+    #   cattr_accessor :subclasses
+    # @example Modifying the scope of a set of methods
+    #   # @!scope class
+    #
+    #   # Documentation for method1
+    #   def method1; end
+    #
+    #   # Documentation for method2
+    #   def method2; end
+    # @since 0.7.0
+    class ScopeDirective < Directive
+      def call
+        if %w(class instance module).include?(tag.text)
+          if object.is_a?(CodeObjects::MethodObject)
+            object.scope = tag.text.to_sym
+          else
+            parser.state.scope = tag.text.to_sym
+          end
+        end
+      end
+    end
+
+    # Modifies the current parsing visibility (public, protected, or private).
+    # If this directive is defined on a docstring attached to an object
+    # definition, it is applied only to that object. Otherwise, it applies
+    # the visibility to all future objects in the namespace.
+    #
+    # @example Modifying the visibility of a DSL method
+    #   # @!visibility private
+    #   cattr_accessor :subclasses
+    # @example Modifying the visibility of a set of methods
+    #   # Note that Ruby's "protected" is recommended over this directive
+    #   # @!visibility protected
+    #
+    #   # Documentation for method1
+    #   def method1; end
+    #
+    #   # Documentation for method2
+    #   def method2; end
+    # @since 0.7.0
+    class VisibilityDirective < Directive
+      def call
+        if %w(public protected private).include?(tag.text)
+          if object.is_a?(CodeObjects::Base)
+            object.visibility = tag.text.to_sym
+          else
+            parser.state.visibility = tag.text.to_sym
+          end
+        end
+      end
+    end
+  end
+end