From: Jeremy McAnally <jeremymcanally@...>
Date: 2008-05-05T01:13:59+09:00
Subject: Uniform RDoc markup

Would there be any resistance to making the markup of the RDoc
throughout the core code more consistent?  Here's the template I like
using:

      Introductory material goes here, where I explain the jist of the
method and mention a few key parameters if I need to.

      ==== Parameters
      * parameter  - Explains all parameters if the list can't be
easily explained in the introduction.

      ==== Options
      * option  - Explains all available options, possible values, and
default values.

      ==== Returns
      * Possible return values...
      * ...if there are a lot of variants dependent on parameters.

      ==== Examples
         # A few examples, documented in comments if possible
         puts "Howdy!"

          # Demonstrate most likely use cases
          puts "Hello!"

If we could come up with a template that works, I'll gladly go through
and start applying it to the standard library and move out from there.

-- Jeremy

-- 
http://jeremymcanally.com/
http://entp.com

Read my books:
Ruby in Practice (http://manning.com/mcanally/)
My free Ruby e-book (http://humblelittlerubybook.com/)

Or, my blogs:
http://mrneighborly.com
http://rubyinpractice.com