Iterating over the registers of a Yardoc `@macro`

Question

I am looking for way to iterate over the registers of a yardoc @macro. I know you are able to use them in something like as follows:

class Post
  include DataMapper::Resource

  # @macro dm.property
  # @return [$2] the $1 $0 of the post
  property :title, String
end

and you are able generate the arguments the registers represent separated by comas as if you were taking a section of an array like as follows:

# @macro dsl_method
# @method $1(${2--2})
# @return [${-1}] the return value of $0
create_method_with_args :foo, :a, :b, :c, String

generates: foo(a, b, c) and returns (String) the return value of create_method_with_args but I am interested in call something like (${2--1}).each do |$arg| and do documentation say each of the params with a single line of documentation.

Answer 1

Unfortunately macros are an extremely simplistic tool to reduce DRYness of docs. We opted out of implementing executable macros due to security concerns (you probably don't want Ruby running in your comments). They aren't really a one-size-fits-all solution to all problems, but they work well in the very simple cases. Plugins are still the recommended way to go for the more complicated cases.

That said, since you would still have to specify the actual parameter documentation somewhere, I don't see how even a plugin would simplify anything for you. If I were you, I would simply define it as you already have, and use @param tags to define each of the arguments separately. For example (let's assume the macro was previously "attached" the way you did in your question):

# @param [String] a documentation for a
# @param [Symbol] b documentation for b
# @param [Hash] c documentation for c
create_method_with_args :bar, :a, :b, :c, Fixnum

That seems pretty reasonable to me, since there's not much else you can DRY up in those docs.