@!method directive with indented method docstring: parser fails to recognize parameter names

[paddor]

What the documentation says:

# @!method quit(username, message = "Quit")
#   Sends a quit message to the server for a +username+.
#   @param [String] username the username to quit
#   @param [String] message the quit message
quit_message_method

What I did:

# My method description.
#
# @param name [Symbol, String] name of the property
# @param conf [Boolean] whether this will be a configuration property
# @!method example_property(new_value = nil)
#   Gets the current property value or sets a new property value.
#   @param [Object] new_value new property value
#   @return [Object] property value
#
def self.create_property(name, conf: false)
  # ...
end

Yard complains:

[warn]: @param tag has unknown parameter name: new_value
    in file `lib/mygem/engines/modules/domain/model/base.rb' near line 217

So I also tried it with the param name on the other side of the [type] specification, like this:

# My method description.
#
# @param name [Symbol, String] name of the property
# @param conf [Boolean] whether this will be a configuration property
# @!method example_property(new_value = nil)
#   Gets the current property value or sets a new property value.
#   @param new_value [Object] new property value
#   @return [Object] property value
#
def self.create_property(name, conf: false)
  # ...
end

No success.

Same goes for an indented @!overload with inindented @param.

How to do this properly?

• OS: [Enter operating system / version here] Ubuntu 22.04
• Ruby version (ruby -v): ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-linux]
• YARD version (yard -v): yard 0.9.28

[lsegal]

Use @overload, not method directives to handle overloads. Note that if you use an overload, all your method documentation must use the same style. You should not mix directive / non-directive tags, i.e.:

# @param name [Symbol, String] name of the property
# @param conf [Boolean] whether this will be a configuration property

The above lines are not part of any overload or method directive and thus wrong. The documentation does not say to do this.

The appropriate documentation, as per @overload docs, should look like:

# @overload example_property(new_value = nil)
#   My method description for overload 1
#   Gets the current property value or sets a new property value.
#   @param new_value [Object] new property value
#   @return [Object] property value
# @overload create_property(name, conf: false)
#   My method description for overload 2
#   @param name [Symbol, String] name of the property
#   @param conf [Boolean] whether this will be a configuration property
def self.create_property(name, conf: false)
  # ...
end

Note that [Object] typing is not required since this is assumed, though you should strongly consider providing a more appropriate type if you're going to use type specifiers at all.

[dmkash]

I'm bumping into this exact issue while documenting methods added by a decorator object. Here's an example of what I have:

class FooDecorator
  # Add methods to `some_object` in order to support the `Foo` functionality
  # @param [FooObject] some_object
  #
  # @!method some_method(arg1, arg2)
  #   Do something cool to support that sweet, sweet Foo functionality
  #   @param [String] arg1 A string argument
  #   @param [Symbol] arg2 A symbol argument
  def self.decorate(some_object)
    def someobject.some_method(arg1, arg2)
      # ... do some stuff ...
    end
  end
end

This results in an UnknownParam error. Is the @!method directive not what I want here?