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.
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.
Edit: see comments for cases where may also want to use custom handlers or the newer directives if your needs extend beyond the limitations of macros and you are fine with using custom YARD extensions or plugins.