YARD: document custom getter/setter pair like attr_accessor

Question

I'm using YARD to document my project. YARD document attributes created with

attr_accessor :some_attribute

in a separate section "Instance Attribute Summary". Now I have another attribute, but with custom setter and getter

def some_other_attribute
  # ...
end

def some_other_attribute= value
  # ...
end

so basically my question is, how can I get YARD to document this pair of setter/getter just like attr_accessor in the previous case, and list some_other_attribute within "Instance Attribute Summary"?

Needless

Answer 1

As of 0.8 (which is in pre-release right now), the @!attribute directive is the recommended way to denote that an object is an attribute. The @attr_* tags are deprecated in favour of this directive. You could also do (in 0.8.0+):

# @!parse attr_accessor :some_attribute

To parse code that isn't necessarily executed by Ruby. Prior to 0.8, you could just add the attr_accessor directly and then redefine the setter/getter as follows:

class MyClass
  attr_accessor :foo
  def foo; something_else end
  def foo=(v) something_else(v) end
end

Ruby shouldn't mind, except that in ruby -w it will warn about method redefinitions. If this bugs you, you can add undef foo, foo= in there too. It's a little messy (if you care about -w), which is why we added things like @!parse and @!attribute.

Rosy

Where would you define @!parse attr_accessor :some_attribute? – Vagary

When mixed attr e.g. attr_reader :some_attribute and def some_attribute=(str). I suggest just adding a # @!attribute [rw] some_attribute and description for both setter and getter and leave the attr_reader with no comment. Else there is overwritte. – Venipuncture

Answer 2

You should be able to use the @attr tag on the class:

# @attr [String] name The name of this object. 
class MyClass
  def name
  end
  def name=
  end
end

There are other tags (like @attr_reader and @attr_writer) than can also be helpful.

Chimera

I don't think it works, not in modern YARD version at least – Demetra