rubyyard

Documenting parameters for macro generated methods with YARD

Give the following input:

class A
  # @!macro [attach] add_setting
  #   @!attribute [rw] $1
  #   @!method $1=(value)
  def self.add_setting(setting)
  end

  # @param value [String] Hexadecimal representation of color
  add_setting :color
end

YARD 0.9.12 generates the following warning (new since ~> 0.8):

[warn]: @param tag has unknown parameter name: value
    in file `test.rb' near line 9

What is the correct way to structure this documentation to avoid the warning? (This pattern is used in rspec.)

Solution

  • You are correct that rspec uses this documentation and you can see that they specify using the defined macro 

    # @macro [attach] add_setting
#   @!attribute [rw] $1
#   @!method $1=(value)
# .....
# @macro add_setting
# Run examples over DRb (default: `false`). RSpec doesn't supply the DRb
# server, but you can use tools like spork.
add_setting :drb

    If you notice the @macro add_setting declaration this tells yard when documenting this method use the add_setting macro. In this case $1 means drb so it will document the drb attribute. (not the individual getter/setter methods)

    As you can see when they are documenting these methods they do not declare a data type because these types may differ for the different documented methods. Instead they specify the default in the description of the method.

    Option 1 (not sure why it works)

    Just define the getter and setter rather than using !@attribute declaration which would look like 

    class A
  # @!macro [attach] add_setting
  #   @!method $1
  #     @return [Object] the $1 of the a 
  #   @!method $1=(value)
  def self.add_setting(setting)
  end
  # @param value [String] Hexadecimal representation of color
  add_setting :color
end

    The @return is important or the warning comes back

    Option 2

    If you really wanted this functionality you could use @overload which would look like 

    class A
  # @!macro [attach] add_setting
  #   @!method $1
  #     @return [Object] the $1 of the a
  #   @!method $1=(value)
  def self.add_setting(setting)
  end
  # @overload color=(value)
  #   @param value [String] Hexadecimal representation of color
  # @macro add_setting
  add_setting :color
  add_setting :name
end

    This will cause the getter method for name and color to be documented as:

    but the setter methods will look like

    because we overloaded color=.

    That being said this doesn't really help you as it would probably consist of individually documenting the methods anyway.

    Other options: