Rdoc how to

Instructions for generating rdoc documentation for crabgrass, as well as best practices for commenting classes and methods.


The idea is to have a web interface documenting crabgrass code so developers can more easily review/find/understand the code.

RDoc in 20 seconds

  1. Regular ruby comments are used to document methods, classes, etc. Simply precede the item you want to document with a comment.
    # open the file
    def open
  2. The comment for a file is pulled from the first comment block.
    # this is a file level 
    # comment.
    # this comment is ignored.
    # this comment documents the open method.
    def open
  3. to hide a method from rdoc, do this:
    # :nodoc:
    def open
  4. optionally, a .document file specifies which files will be included in that folder (.rb and .rbw are automatically included)
  5. RDoc uses SimpleMarkup. The format for simple markup is here

RDoc resources


  1. http://rdoc.sourceforge.net/


  1. on-ruby.blogspot.com/2006/06/rdoc-from-...

Interesting Examples

  1. camping.rubyforge.org/files/README.html

Running RDoc

We should configure rdoc to run whenever there are changes checked in.

Here is the option list currently being used (to create this output):

rdoc --main README_RDOC --all --diagram --force-update --image-format png --inline-source --line-numbers --title 'Crabgrass Rdoc' --op doc/rdoc app lib mods test tools README_RDOC doc/ADMIN_README doc/GEMS_README doc/MULTILINGUAL_README doc/SPHINX_README


A preliminary attempt is up at faloona.net/brandon/crabgrass-rdoc/


wow, that is so super cool. how did you get the README to look formatted right. Did you have to change the markup to be rdoc?

Can you post some examples of methods documented with rdoc?


I’ve uploaded the two files i altered. The rest was just rdoc doing it’s magic (+ several command line options).

If we want to retain the readability of the main README, we should create a copy for rdoc to use as the initial file displayed.

To add item specific comments, simply precede the method/class/etc with a comment! (see attached app/controllers/account_controller.rb) For files, the first comment block is used. Comments after that, unless they directly precede a method or class, are ignored.


nice!!! wow.