90

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.
Seanny123
  • 8,776
  • 13
  • 68
  • 124
Levi Hackwith
  • 9,232
  • 18
  • 64
  • 115

3 Answers3

32

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.

3limin4t0r
  • 19,353
  • 2
  • 31
  • 52
bk1e
  • 23,871
  • 6
  • 54
  • 65
  • 5
    I was just looking for this. Note that http://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** – serverhorror Mar 15 '11 at 20:18
  • 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`](http://daringfireball.net/projects/markdown/) mentioned at http://rdoc.rubyforge.org/RDoc/Markup.html#label-Supported+Formats - am I missing something? – FriendFX Nov 20 '13 at 05:06
  • 3
    rubyforge links dead. – Ciro Santilli OurBigBook.com Sep 02 '14 at 15:44
  • 3
    http://docs.seattlerb.org/rdoc/RDoc/Markup.html is the only working link left on this page. Edit your answer to use that one? – Mark Amery Oct 19 '14 at 19:44
  • 1
    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](https://github.com/ruby/ruby/blob/0d3591f250bfe90805cac3c2d5bbfcadb720df37/file.c#L2067-L2077) – gene_wood Jun 08 '15 at 20:28
  • 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. – wmakley Feb 01 '21 at 17:00
22

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

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

3limin4t0r
  • 19,353
  • 2
  • 31
  • 52
Myers Carpenter
  • 939
  • 1
  • 9
  • 12
  • 4
    This one also looks pretty current: http://docs.seattlerb.org/rdoc/RDoc/Markup.html – Steve Jul 15 '14 at 19:39
  • 3
    old link is dead now with new version. current: http://ruby-doc.org/gems/docs/r/rdoc-4.1.2/RDoc/Markup.html – m.silenus Dec 22 '14 at 05:58
  • 2
    This is absurd. All the ruby-doc links are dead but this seems to work: http://ruby-doc.org/stdlib-2.2.3/libdoc/rdoc/rdoc/RDoc/Markup.html But for how long...? – bronson Oct 12 '15 at 07:56
  • 1
    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. – wmakley Feb 01 '21 at 17:03
0

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

Sony Santos
  • 5,435
  • 30
  • 41