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 # …

Is there a gem, or a way to do this that means I can avoid trying to write a Yard extension?

Precontract

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.

Precontract

Yes, it looks nice, but my YARD doesn't generate a proper clickable link to the original method. – Uzial

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=

Brittbritta

Answer 3

This works for me.

# @!method do_this
#   @return [mixed] See {Instance#do_this}.
# @!method do_that
#   @return [mixed] See {Instance#do_that}.
delegate *[
  :do_this,
  :do_that,
], to: :instance

Other:

• gem yard-delegate doesn't work for such construct. It's pretty old though.
• Putting # @!method above individual :method doesn't work (ignored by YARD).
• Better specify actual method return value, it produces a list more comfortable for the reader.

Uzial