Is there a good, solid reference for proper RDoc syntax?

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.

Since RubyForge has been retired, here is a new link:

http://ruby-doc.org/stdlib-2.5.1/libdoc/rdoc/rdoc/RDoc/Markup.html