YARD - resource handler - documenting defs declared in .each block

Question

How can I write documentation for definitions that are gathered in an .each block? My particular case is Middleman, but I think the problem is more generalized, and Google is being disappointing today.

For example:

def manipulate_resource_list(resources)
    resources.each do |resource|
      # Provides a greeting
      # @return [string] Returns the greeting.
      def resource.hello_world
        'hello, world'
      end
    resources
end

I've gotten this far:

class ResourcesHandler < YARD::Handlers::Ruby::Base
  handles :def
  namespace_only

  def process
    if statement.method_name(true).to_sym == :manipulate_resource_list
      parse_block(statement.last.first.last.last, :owner => self.owner)
    end
  end
end

But this is really kind of crappy because I have to actually document the code like this:

      # @!method hello_world
      # Provides a greeting
      # @return [string] Returns the greeting.
      { blank line 1 }
      { blank line 2 }
      def resource.hello_world
        'hello, world'
      end

… and I have to worry about the YARD::Handlers::Ruby::MethodHandler: Undocumentable method defined on object instance when YARD encounters the def resource.hello_world.

Note: I want to document in the code, near the declaration, not in some remote part of the file.

Any idea how I can improve my YARD resource handler to make this more natural?

score 0 · Answer 1 · answered Apr 12 '16 at 02:56

Well, I ended up using this:

class ResourcesHandler < YARD::Handlers::Ruby::Base
  handles :def
  namespace_only

  def process
    if statement.method_name(true).to_sym == :manipulate_resource_list

      # Block consists of everything in the actual `do` block
      block = statement.last.first.last.last
      block.each do | node |
        if node.type == :defs
          def_docstring = node.docstring
          def_name = node[2][0]
          object = YARD::CodeObjects::MethodObject.new(namespace, "resource.#{def_name}")
          register(object)
          object.dynamic = true
          object[:docstring] = def_docstring
          object[:group] = 'Resource Extensions'
          puts node.type
        end
      end
    end
  end
end

YARD - resource handler - documenting defs declared in .each block

1 Answers1