Question

I’m looking for a good, solid reference for proper RDoc syntax. Recommendations? I can’t seem to find anything that clearly shows:

1. How to document class methods and their parameters
2. How to document what a class or class method does.

Answer 1

An official rdoc example can be found here, with its GitHub source.

The documentation at rdoc.rubyforge.org seems to be more complete than the version at rdoc.sourceforge.net (which incidentally has a 2003 modified date).

Also, there is a great source of examples: the Ruby core and stdlib documentation. For example, take a look at one of the class methods from the File class:

File.atime(file_name) => time

Returns the last access time for the
named file as a Time object).

File.atime("testfile") #=> Wed Apr 09 08:51:48 CDT 2003

You can view the original source code, including the RDoc markup, by clicking on the first line (in the actual RDoc page, not in the quote I included in this answer). In this case, the method was implemented in C, but the RDoc formatting is the same as if it was implemented in Ruby:

/*
 *  call-seq:
 *     File.atime(file_name)  =>  time
 *  
 *  Returns the last access time for the named file as a Time object).
 *     
 *     File.atime("testfile")   #=> Wed Apr 09 08:51:48 CDT 2003
 *     
 */

From this you can see that call-seq: lets you replace the method name and parameters with text of your choosing, which is very useful for class methods. It also shows how you can display example code in a monospaced font by indenting it, similar to Markdown.