Question

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?

Answer 1

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