I just started to document a rails application. I know this is actually done by rdoc, so I followed some rdoc guides regarding syntax and so on, but I got stuck when I tried to describe attributes of models, validations and the relationship between models, mostly because these things are part of ActiveRecord. So I wonder if there is some guide or a good practice regarding how to document a rails application or if there is something I'm missing?
I know that I could put all of this in the class description, but I wonder if there is a way more closely tied to the declaration itself (has_many, validates_presence_of, etc.) and what about the attributes?
I personally prefer YARD - http://yardoc.org , as it does a better job in documenting IMHO. I don't know if there's a specific handler for Rails available, but it's quite easy to write one - http://yardoc.org/guides/extending-yard/writing-handlers.html A good example might be the attribute handler - part of the yard gem: lib/yard/handlers/ruby/attribute_handler.rb