Source Code Documentation in Ruby: RDoc for Ruby CDK

Rich Apodaca — Tue, 05 Dec 2006 14:36:00 +0000

Good source code documentation tools can greatly enhance developer productivity at almost no cost. By eliminating the need to dig through source code files for documentation, tools like Java's Javadoc are invaluable for quickly seeing the big picture of a new piece of software. They are also handy as a quick reminder for more familiar APIs.

Ruby comes complete with a source code documentation tool called "RDoc." Running RDoc over your Ruby source produces a group of cross-linked HTML files in a manner analogous to Javadoc.

The Ruby CDK distribution contains HTML API documentation generated by RDoc and located in the doc subdirectory. This documentation was automatically generated with a task written for Ruby's build system, Rake. This task, contained in the file Rakefile, is shown below:

Rake::RDocTask.new do |rdoc|
  rdoc.rdoc_dir = 'doc'
  rdoc.title    = "Ruby CDK"
  rdoc.rdoc_files.include('README')
  rdoc.options << '--line-numbers'
  rdoc.options << '--inline-source'
  rdoc.options << '--main' << 'README'
  rdoc.rdoc_files.include('lib/**/*.rb')
end

Unlike Java's build tool, Ant, Rake isn't based on XML. Instead, the entire build system is pure Ruby. This introduces a level of clarity and brevity into the build process that simply doesn't exist with Ant.

Ruby CDK's RDoc task extends the built-in Rake task named appropriately enough RDocTask. The customization of this task lies completely within the constructor block. Among other modifications, this block activates inlined source code with line numbers, a very handy feature given Ruby's highly dynamic nature.

As a convenience, Ruby CDK's RDoc documentation is now available online. The API and schema documentation for my other software projects will appear soon on Depth-First in the sidebar to the right.

Depth-First: Tag rdoc

Source Code Documentation in Ruby: RDoc for Ruby CDK