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?

Cherianne

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

Aprilaprile

I think this is a very iteresting approach, I think that the only problem is that it seems a little young still and have a learning curve more pronounced than I was expecting, nevertheless I think it have a lot of potencial. I even started to imagine some nice features, like feed the database with documentation from the migrations, and then get that documentation into the generator, in that way you can kill two birds with one stone, the application documentation and the database documentation. – Cherianne

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.

Briannebriano

I like this approach, for the development team I think will work, but in some cases you need an actually document, a document that may will not be used strictly for a developer, but by a guy who actually don't care about the tests (and don't have to). – Cherianne

In the other hand, validations isn't always easy to interpret, even for a programer, for exemple in my aplication I have some validation for some numeric attributes that have to be between -180 and 180. This is because this atribute represent a latitude value and this values can only be in this range. And this it's just an easy one, I have other validations that include relationships and restrictions more abstract, that even when I readed again the code isn't clear at the first time. – Cherianne