In preparation for my RDoc preso at the May Rails Oceania Sydney meetup I’ll be a doing a series of articles on RDoc and how to document Ruby, and Rails, code. This article is the first in the series.

I’m still trying to come to terms with the best way to share the information in my Rails presentations to a wider audience; and rather than look like a blue wiggle, or have some downloadable version of the preso; I thought I’d just document things with some proper, well-written articles on the topic.

I’d also like to think that those who see the articles before seeing the presentation will get a lot more out of the experience.

So here we go…

What’s RDoc?

You know the Rails documention, the ruby-doc.org API docs, that crazy caboo.se edge rails docs thang and why’s crazy lookin Camping docs? They’re all the result of RDoc: the defacto Ruby documentation generation tool.

As a truely pragmatic programmer should, Dave Thomas (yes, that Pickaxe guy) crafted RDoc back in 2001 when Andrew and he were beginning to teach and publish Ruby learning material, and the community were in need of a Ruby documentation tool. According to wikipedia’s RDoc page:

[RDoc] is the embedded documentation generator for the Ruby programming language. It analyzes the Ruby source code, generating a structured collection of pages for Ruby objects and methods. Code comments can be added in a natural style.

RDoc is included as part of the Ruby core distribution.

RDoc is useful even if the target source code does not contain explicit comments. RDoc will still parse the classes, modules, and methods, and list them in the generated API files.

RDoc also provides the engine for creating Ruby ri data files. ri is (more or less) Ruby’s version of man pages, serving up API information from the command line.

RDoc’s grouse features

• The command-line documentation generation tool, rdoc
• The command-line documentation search tool, ri
• A nicely documented Ruby library for programatically invoking doc generation, or playing with bits to get access to all the same info used to generate docs
• RDoc::usage, for command-line tools needing to output usage information
• Code diagrams via Graphviz integration
• Nice layered design with sensible abstractions, allowing simple customisation of page output and other fun bits.

Our first documented Ruby class

Installing RDoc is simple: you don’t have to. RDoc is packaged with Ruby so you can start using it today.

Let’s make our first documented Ruby class. Save the following into my_first_documented_class.rb:

# An example class
class MyFirstDocumentedClass
  # A public method
  def a_public_method
  end
end

You’ll then want to run rdoc on it:

$ rdoc my_first_documented_class.rb 

       my_first_documented_class.rb: c.
Generating HTML...

Files:   1
Classes: 1
Modules: 0
Methods: 1
Elapsed: 0.045s

Congratulations! You’ve generated your first Ruby documentation by hand.

You’ll notice a doc directory has been generated, with an index.html file inside containing your faux-western-buddhist, life-changing code comments.

Start playing

All Rails apps contain some pre-baked RDoc integration in the form of a doc directory, a doc/README_FOR_APP “main” doc file and some Rake tasks, which you can see below:

$ rake -T doc
rake doc:app              # Build the app HTML Files
rake doc:clobber_app      # Remove rdoc products
rake doc:clobber_plugins  # Remove plugin documentation
rake doc:clobber_rails    # Remove rdoc products
rake doc:plugins          # Generate documation for all installed plugins
rake doc:rails            # Build the rails HTML Files
rake doc:reapp            # Force a rebuild of the RDOC files
rake doc:rerails          # Force a rebuild of the RDOC files

To generate documentation for your Rails application, simply execute rake doc:app, open doc/app/index.html and bask in your freshly baked, and most probably barren, documentation.

Where from here?

Look out for a more thorough intro into the conventions of documenting your classes, methods and modules; the various types of formatting you can use in your documentation; and, creating your own funky templates.