Tuesday, October 20, 2009

RDoc: I'm converted

Working on a new rails app yesterday I happened upon a file I hadn't read before: doc/README_FOR_APP

Use this README file to introduce your application and point to useful places in the API for learning more. Run "rake doc:app" to generate API documentation for your models and controllers.

So I ran the rake task and looked at what it generated. Wow. I'm not a big fan of tests in rapidly changing prototype code, but I LOVE documentation when it is easy to add and easy to find. This rake task generates rdocs for your application. If you don't know, rdoc notes are very easy to add to your code.

The rdocs are hyperlinked and have the method bodies inline so you can drill down for more details when you need them. This really helps when you are working on a large code base and can't remember everything about it. Tests are good, but understanding the code you're working with is primary.

No comments: