Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Document model attributes with YARD

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 like to document the model attributes to one, record the list of available attributes on a model and two, to describe their semantic meaning.

I wasn't able to find any special support for this in YARD and I'm basically left with simply listing out the attributes in the class comments. Is there a way to document the dynamically generated model attributes so that they appear in the documentation like standard attributes/methods?

P.S. I've used the annodate-models gem to generate a basic schema dump at the top of the class listing but that's not really what I want.

like image 513
Paul Alexander Avatar asked Mar 18 '11 05:03

Paul Alexander


1 Answers

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.

like image 189
Joshua Muheim Avatar answered Oct 05 '22 01:10

Joshua Muheim