Documenting def_delegators with Yardoc

Question

I have a class that uses the def_delegators method from the Forwardable module. I haven't found a way to get Yardoc to output documentation for it. I've tried using a macro but it won't output anything for these particular methods (everything else in the file is fine, and there are no errors), and I've several def_delegators of differing lengths.

e.g.

class A
  extend Forwardable
  # other code…

  # @!macro
  #   @see Array#$1
  #   @see Array#$2
  #   @see Array#$3
  def_delegators :@xs, :size, :<<, :blah # …

If anyone knows of a gem or a way to do this that means I can avoid trying to write a Yard extension to do this, I'd be very grateful.

Answer 1

After more experimentation I found that this worked quite well:

  # @!method size
  #   @see Array#size
  # @!method <<
  #   @see Array#<<
  # @!method blah
  #   @see Array#blah
  def_delegators :@xs, :size, :<<, :blah # …

There is quite possibly a way to do this in one or two lines, but compared to the work writing an extension I find this very acceptable.

---

Update:

I've just found this will link to the delegated methods' documentation better:

  # @!method size
  #   @return (see Array#size)

This would take the already documented return value from the Array#size method. I expect the other tags will do this too. It's still quite verbose, but acceptable.

Answer 2

You need to combine the two concepts. Use @!macro to produce a @!method.

Below is my version of a solution. But the problem for me is OptParser is not included so the See also has no link. The second downside is the method's signature, parameters, and return value is not described. And the third ick is the string OptParser is fixed but really needs to able to be adjusted (parameterized).

If it was forwarding to a method included in the project, then you could use (see Foo#method) (no @ sign in this case) and whatever is at Foo#method would be copied into the new source. This would be done by doing (see Foo#$2) inside the macro -- with the paren's included. See YARD's Reference Tags

# @!macro [attach] def_delegators
#   @!method $2
#     Forwards to $1.
#     @see OptParser#$2
def_delegators :opt_parser, :order!
def_delegators :opt_parser, :on
def_delegators :opt_parser, :on_head
def_delegators :opt_parser, :on_tail
def_delegators :opt_parser, :help
def_delegators :opt_parser, :add_officious
def_delegators :opt_parser, :banner
def_delegators :opt_parser, :banner=
def_delegators :opt_parser, :program_name
def_delegators :opt_parser, :abort
def_delegators :opt_parser, :release
def_delegators :opt_parser, :release=
def_delegators :opt_parser, :version
def_delegators :opt_parser, :version=