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

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.

Surprising

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.

Pyromorphite

I was just looking for this. Note that rdoc.rubyforge.org/RDoc/Markup.html has the (as it seems) official spec. Search for: RDoc Markup Reference Darn! I really should have read the second comment too – Haymow

Not sure if that applies to newer versions as well, but with my 1.9.3 ruby, it doesn't seem to support the --markup option (trying to use markdown mentioned at rdoc.rubyforge.org/RDoc/Markup.html#label-Supported+Formats - am I missing something? – Giveaway

rubyforge links dead. – Edomite

docs.seattlerb.org/rdoc/RDoc/Markup.html is the only working link left on this page. Edit your answer to use that one? – Avalon

I wasn't able to find the link to the source code as mentioned in the answer (which says it's accessed by "clicking on the first line (in the actual RDoc page, not in the quote I included in this answer)". Here's the link to the Ruby File module source code – Ledet

Most of these links are broken or do not contain complete answers. There is only a smidge of markup reference, and nothing about how to document parameters, exceptions, return types, etc. – Albumose

Answer 2

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

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

Pedant

This one also looks pretty current: docs.seattlerb.org/rdoc/RDoc/Markup.html – Fluid

old link is dead now with new version. current: ruby-doc.org/gems/docs/r/rdoc-4.1.2/RDoc/Markup.html – Bidle

This is absurd. All the ruby-doc links are dead but this seems to work: ruby-doc.org/stdlib-2.2.3/libdoc/rdoc/rdoc/RDoc/Markup.html But for how long...? – Anathematize

This page contains only the most cryptic documentation for handling method parameters, and nothing about return types, exceptions, etc. Very difficult to make any sense of. – Albumose

Answer 3

IMHO the best official RDoc markup reference is MarkupReference, along with its Github source.

Artificial