How to document a rails application?

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

Answer 2

Remember your tests are part of the documentation (for developers), particularly if you are using Cucumber where scenarios are easy to read. If you keep your methods very short and there is a test method with a descriptive name e.g. "should set the users name" I find I typically don't need comments on the method.

Validations or other parts of Rails I would not document. Part of being a Rails developer is understanding how these work, I think it is a fair assumption that another maintainer of your code reading it down the road will know validations, or other things built in to Rails. By that same logic, if you can use features of the framework or happy paths (not deviate much) with [documented] third party code, a lot of the documentation will be written for you.