Ruby yard documenting DSL method definition AND its uses>

Question

Ruby with Yard 0.9.8. I'm defining custom attribute accessors in a ClassMethods module that will be extended into classed and other modules.

What I want to do is document what the DSL accessor methods do and attach that to their definitions, but have invocations of the method inherit generic docstrings about the parameters, return value, and such for each use.

However, defining the DSL docstring with @!macro [attach] on the definition of the accessor method isn't workable, because:

1. The macro parameters ($1, &c.) don't match correctly between the accessor definitions and the accessor invocation, and
2. I don't want the "How this attribute declarator works and is invoked" docstring to show up for both the definition and the uses.

So far the best I've been able to do to get the desired result is to define two macros:

• @!macro [new] doc.procject.classmethod.foo.def, which describes the declaration in the normal way you would for any method, and
• @!macro [new] doc.project.classmethods.foo.use, which includes the generic DSL documentation such as you'd see for attr_accessor :foo with no user-supplied docstring at all.

And then putting @!macro doc.project.classmethod.foo in the method's definition docstring, and for each actual invocation have some attribute-specific text followed by @!macro doc.project.classmethod.foo. Or possibly @!macro [attach] ...

All this seems suboptimal and it feels like I'm missing something crucial. The tag documentation has a few examples, but they do not show how the result appears.

For example, here's some simple code that shows how I'd like to see the output look:

module Outer
  module ClassMethods

    # Describing the **class method** -- the declaration.

    # @!method dsli(*args)
    # This class method declares one or more DSL interface variables.
    # @param [Symbol] args
    # @return [void]
    def dsli(*args) ; end
  end

  extend(ClassMethods)

  # Describing the **invocation** of the class *method* to create
  # an *attribute*.

>># @!attribute [rw] hoipolloi
  # This variable controls the frobbing of the potrzbi.
>># Only instances of class DSL::Thingie can be stored in this
>># attribute; any other class will result in a TypeError exception
>># being raised.
>># @overload hoipolloi
>>#   @return [DSL::Thingie,nil] the current value of the attribute.
>># @overload hoipolloi=(newval)
>>#   Sets a new value for the attribute.
>>#   @param [DSL::Thingie] newval
>>#   @raise [TypeError] if `newval` is of any class other than
>>#     DSL::Thingie.
>>#   @return [DSL::Thingie] the new value.
  dsli(:frotrzbi)

end

This sort of describes what I'd like to have happen. All the lines prefixed with >> should be inherited (somehow) from the dsli method declaration. I want to embed some of the invocation information in the class method's docco. The method's documentation should talk about how, but the docco for any attributes it declares should talk about what. The class method's documentation applies only to its declaration, but the inherited documentation applies to all the attributes defined with it.

I have not been able to get this to work with YARD macros (a requirement in order to insert the proper names of the attributes, &c.)

Is there a better way to define distinct docstrings for DSL methods, one for each method's definition and another for invocations of the method à la [attach]?

Thanks!