Document model attributes with YARD

Question

I\'m using YARD to generate docs for my rails app with makrdown as the script parser. Most of the documentation features just work great right out of the box. However, I\'d also

Answer 1

After quite a while searching around, I punted and manually added the documentation for the attributes to the model files. This is certainly not ideal, but hopefully the model structure won't change a whole lot.

I created a .yardopts file for the project and used the yard command-line options to create two new tags for marking these up:

--type-name-tag 'attribute:Attributes' --type-name-tag 'association:Associations'

These provide me with specific tags for marking up the attributes and associations; they will show up grouped under the "Attributes" and "Associations" headings in the documentation. I can add this:

# @attribute name [String] The name of the object
# @association relatedObjs [Array<AnotherClass>] Objects needed to perform a certain function

Maybe someone will write a plugin for YARD that will parse out the annotate-models output.

Answer 2

It seems that YARD now has its own @!attribute (notice the exclamation mark) tag for this purpose:

http://rubydoc.info/docs/yard/file/docs/Tags.md#attribute

Example:

class Task < ActiveRecord::Base
  # @!attribute name
  #   @return [String] The name of the task.

  # @!attribute description
  #   @return [String] The description of the task.

  # @!attribute active
  #   @return [Boolean] Marks whether the task is active or not.
end

This will result in nice documentation of your attributes. The only thing to watch out is that you always keep your documentation up to date because nobody will check whether you remove an attribute from your documentation when you deleted it from the database, etc.