@option tag does not pick up keyword arguments

[kopischke]

Ruby 2 style keyword arguments documented via the @option tag are ignored in the final YARD documentation – instead, the generic description for the assigned option hash name is displayed.

[lsegal]

The @option tag does not, and likely will not, support keyword arguments due to the semantic of the tag itself. One of the required arguments of the option tag is the name of the (Hash) parameter that the options can be found in, something that keyword arguments would not work well with. For example, this syntax would not support keyword args:

# @option opts x [Fixnum] the Nth value
def foo(opts={}) end

Note the "opts" there. Right now it should not even be possible to specify keyword args using the @option tag, given the syntax of the tag. The fix would either be to make the parameter name optional, which would be extremely complicated for parsing, or perhaps more appropriately, introduce a new @keyword tag to represent the slightly different semantic of kwargs.

[kopischke]

Currently, I’m using the @param tag as a workaround, but that only works for explicitly declared kwargs (i.e. def foo(**kwargs), which is Ruby 2’s equivalent to def foo(kwargs={}), does not work), obfuscates the need to use Ruby 2 kwargs syntax for arguments and might also be the cause for #728.

If (just a raw thought) using something like kwargs as a mandatory option Hash name for the existing tag wouldn’t work, then a @keywordargument may indeed be the way to go; however, some kind of tag would still need to pick up the double-splatted kwargs Hash.

[lsegal]

Can you provide the docstring you are testing that is behaving incorrectly?

[kopischke]

Sure:

# Guess the file’s text encoding.
# @param guessers [Array<Guesser>] the guessers to use, in order.
# @option options [Boolean] :with_dummies should dummy Encodings be included in the guesses?
# @option options [Float] :good_enough the confidence level >= which no further guesses are needed.
# @option options [Float] :never_mind the confidence level < which guesses are discarded.
# @return (see self.guess_encoding)
def guess_encoding(*guessers, **options)
  File.guess_encoding(self, *guessers, **options)
end

I only specify **options because the class method File.guess_encoding explicitly declares the kwargs and I don’t want to rewrite the signature every time that method changes. Currently, I work around the issue by wrapping the class method param tags in a macro and using that in the instance method docstring.

[matheusmoreira]

I am making heavy use of new Ruby features such as keyword arguments, so I would appreciate this feature. I am in favor of adding a @keyword tag.

1. A double splat (**) variable is an ordinary hash containing keyword arguments
   • It can be documented with @option and @param tags
2. Keyword arguments and hashes are semantically different
   • Despite the fact the former is implemented on top of the latter
3. It is possible to determine the default value of a keyword from the method signature
   • Saves typing and space, making documentation concise
4. The hash variable holding the keyword arguments is hidden by default
   • Only the key and the value type need be specified
     • The key will always be a symbol, so there is no need for a preceding colon (:)
     • The value type can be inferred from the default value
       • Or manually overridden, if the case calls for it

[chendo]

+1. I'm heavily using keyword arguments at the moment. I've also noticed that yard doesn't like required keyword arguments at this point.

[error]: Unhandled exception in YARD::Handlers::Ruby::MethodHandler:
[error]:   in `lib/routing_manager.rb`:13:

    13: def initialize(context:)

[greyblake]

+1.

[error]: Unhandled exception in YARD::Handlers::Ruby::MethodHandler:
[error]:   in `app/interactors/creator.rb`:46:

    46: def initialize(logger:, api:)

[lsegal]

The above change plus the merged #785 PR should allow you to use kw arg splats alongside required kwarg params, though the semantics are admittedly a little wonky. A @keyword tag should resolve the larger problem in the future, but I think the above should be a reasonable stopgap.