When working with rails, the Rails Framework Documentation and Ruby Documentation are invaluable resources.

With RDocs like these, you can quickly find information on classes, modules, methods etc. and also check out the source-code to help you better understand the code you are using.

Here is a quick tutorial to help you build your own RDocs for your application or plugin so they can be easily understood by others using your code.

To build the basic documentation for your app, all you have to do is enter the following in your terminal window:

rake doc:app
Generating HTML...

Files:   28
Classes: 17
Modules: 12
Methods: 108
Elapsed: 1.914s

This will create a new folder in your application’s root directory called doc and a sub-folder called app. In this folder you’ll find a bunch of html files RDoc has just generated for you.

Open the newly generated index.html (doc/app/index.html) and you should see a page similar to the Ruby Documentation with a list of all your app’s files, classes, modules and methods.

Pretty cool huh?

To add documentation for your methods, explain what each does and give example usage, simply add comments to your code above the module, class or method you want to document. For example:

# User records should require:
# * first_name
# * last_name
# * email
# all other attributes are optional
class User < ActiveRecord::Base

  # returns the first_name and last_name attributes separated by a space
  def name
    "#{first_name} #{last_name}"
  end

end

These comments will be included as descriptions when you build your rdocs.

If you notice, there are asterisks “*” preceding the three attributes listed above the user class. These will be converted to an HTML unordered list with the asterisks marking the start of each list item. Unordered lists can also be delineated with “-” dashes.

To add an ordered list, simply start each list item with a number or letter followed by a period.

# a. list item a
# b. list item b
# c. list item c

To add HTML headers to your docs, simply add an equals sign after the comment like so:

# = Header1
# == Header2
# === Header3
#
# note - the spaces between '#' and '=' are required

One equals sign for h1, two equals signs for h2 etc.

To style the text in your documentation you can use html tags or use textile just like on Handy Rails Tips.

Bold text is wrapped in *asterisks* or <b></b> tags, italics are wrapped in _ underscores_ or <em></em> tags and typewriter text is wrapped in +plus signs+ or <tt></tt> tags.

RDoc will automatically convert urls to html links and urls which point to image files are automatically converted to html images.

Preventing RDoc From Including Certain Comments

There will undoubtedly be times when you want to leave comments for yourself, comments that should not be added to your documentation. For example, annotations. To prevent RDoc from documenting a block of comments, simply start a line with two minuses “- -”, to start documentation again, start a comment line with “++”.

#--
# these lines of text
#  will be ignored
#
#++
# these lines of text
# will be documented
#

Building documentation for plugins & current Rails version

If you’re working offline but need to access the Rails Framework Documentation you can actually build this into the doc folder on your app provided you have a frozen version of rails in your vendor/ folder. You can build the rails RDocs with the following rake command:

rake doc:rails

To create RDocs for a plugin, simply enter:

rake docs:plugins

or to create docs for a specific plugin:

rake docs:plugins:my_plugin

These will also be added to subfolders in doc/.

Check out the documentation for RDoc. There are tons of other options you can implement when creating your own RDocs.