Everyday Rails

3 Rails documentation tools

By Aaron Sumner, October 16, 2010. File under: .

If you’ve been using Reek to help in refactoring your Rails applications, you might run across warnings of Irresponsible Modules— that is, code with no comments to help explain what it does. A common knock on the Rails community is that we don’t document our code. I hate to admit it, but it’s fair. My own Rails project folders are full of uncommented methods and mysterious model attributes. If I can’t remember specifics about my code, how can I expect someone else to pick it up?

The good news is there are quite a few documentation tools out there. Here are three you can get started with quickly to bring your application’s code documentation up to speed.

annotate-models

The first tool is an oldie, but still works great: The annotate-models gem refers to your database schema and adds field details in the comments of the corresponding model. Install the gem, cd into your Rails project directory, and type annotate to add this documentation to your models. You can also document your tests, specs, and factories—see the GitHub repository for more details.

RDoc

Now that you’ve got your models annotated (and have added some descriptive comments to your controllers, right?) you can turn it into browser-friendly HTML using the following built-in Rake task:

  $ rake doc:app

Be sure to also edit the file doc/READ_ME_FOR_APP; that’s what the Rake task uses for your documentation’s starter file. Open doc/app/index.html in your browser to access your app’s documentation.

Rails ERD

Finally, how about some visual documentation of how your models relate to one another? Check out Rails ERD a new gem that creates nice PDF entity-relationship diagrams for your apps. It’s easy to install, customizable, and very well documented. Take a look at the gallery of ERD examples from popular open source Rails projects to get a feel for how it works. The rendered PDF saves to your application root by default—I check this into my source control for other developers (not to mention for my own reference).

Other tools

This list is by no means exhaustive. Refer to Ruby Toolbox’s list of Ruby documentation tools for more options.

Discussion

Follow along on on Mastodon, Facebook, or Bluesky to keep up-to-date with my latest posts. Better yet, subscribe to my newsletter for updates from Everyday Rails, book picks, and other thoughts and ideas that didn't quite fit here.
Buy Me A Coffee

Test with confidence!

If you liked my series on practical advice for adding reliable tests to your Rails apps, check out the expanded ebook version. Lots of additional, exclusive content and a complete sample Rails application.

Newsletter

Ruby on Rails news and tips, and other ideas and surprises from Aaron at Everyday Rails. Delivered to your inbox on no particular set schedule.