Documentation of the anonymous block forwarding

[konalegi]

It's more like a question, is there a way to document anonymous block forwarding introduced in ruby 3.1?

def meth(&)
    ...
    another_meth(&)
    ...
end

I've tried # @param & [Proc] txt, but it didn't help. Sorry if I've missed that from documentation.

[lsegal]

I believe that this is currently unsupported behavior, but if someone wants to throw together a pull request, it can be.

[jcouball]

I have been having the same problem.

[lsegal]

Just FYI:

Generally speaking this is no different of a situation than arg forwarding via *args. Since YARD's static analyzer cannot determine which method you are forwarding to (and what parameters are being forwarded), in this case you would use an @overload tag to manage the dynamic parameters of your method call and define them explicitly. Something like:

# @overload some_method(&block)
#   @yield [name] the block to yield
#     @yieldparam name [String] the name to yield
def some_method(&) forward_to(&) end

You can throw in a @!macro to DRY up the docs and rely on a bit of reuability

# @!macro orig_meth_fwd
#   @overload $0(&block)
#     @yield [name] the block
#       @yieldparam name [String] the name to yield

# @!macro orig_meth_fwd
def another_meth(&) orig_meth(&) end

# @!macro orig_meth_fwd
def another_other_meth(&) orig_meth(&) end

# The original method
# @!macro orig_meth_fwd
def orig_meth(&block) end

(edit: updated code example to be block specific)

I'm going to close this issue as not directly covered by YARD core. Since YARD correctly parses the method (just like it would with *args overloading and other use cases), this seems to be behaving as expected.

[jcouball]

Thanks @lsegal I'll give that a try.