From: Eric Hodel <drbrain@...7.net>
Date: 2008-05-08T07:46:05+09:00
Subject: Re: Uniform RDoc markup

On May 4, 2008, at 09:13 AM, Jeremy McAnally wrote:

> 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.

I prefer plain and simple as it is more pleasant to read than all this  
boilerplate.  Much of the current standard library's documentation is  
pleasant to read as ri (if occasionally densely packed with  
information, like String#split).

Actually, I can't think of much of the core library that has more than  
three arguments, and none of it that has any hash-style options.

As a counterpoint, here's some RDoc I just wrote:

class Gem::Dependency

   ##
   # Uses this dependency as a pattern to compare to the dependency  
+other+.
   # This dependency will match if the name matches the other's name,  
and other
   # has only an equal version requirement that satisfies this  
dependency.

   def =~(other)
     # ...
   end

end

I use consistent ruby vocabulary to describe what this #=~ does  
without using a bunch of boilerplate.

It may be unclear that you could use a regular expression in the name  
of a dependency, but I have implied that by using "match" instead of  
"equal".  The addition of an example might help.