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:
- name => Object
- Returns the name of the a
- color => Object
- Returns the color of the a
but the setter methods will look like
- name=(value) => Object
- color=(value) => Object
- Parameters:
- value(String) -- Hexadecimal representation of color
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:
- Ignore the warnings
- quite all warnings completely
-q
- Checkout this Thread
