Overview¶

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
    ....
   end
   

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¶

Docs¶

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

Tips¶

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