From: Phil Hagelberg <phil@...>
Date: 2008-05-05T05:37:48+09:00
Subject: Re: Uniform RDoc markup

"Jeremy McAnally" <jeremymcanally@gmail.com> writes:

> Would there be any resistance to making the markup of the RDoc
> throughout the core code more consistent?

I would be very much in favour of seeing stronger conventions applied
throughout the Ruby community in the standard library, in gems, and
elsewhere. That's one of the things I miss from writing Emacs Lisp; it
has very specific guidelines[1] (The first line should be a summary
under 67 characters, use the active voice for commands, write
metasyntactic variables in caps, etc.) and this is very helpful for
ensuring consistency. In fact, some of the guidelines can even be
checked programmatically[2]. In Ruby we have the mechanics of formatting
explained fairly well, but I believe more suggestions about style and
structure would be helpful.

I think Jeremy's suggestions are good. I would add a clearer distinction
between functions that are called for side-effects and functions that
are called just for their return value, and I would separate out the
parameters section into required, optional, and "options" keyword-style
parameters.

-Phil

[1] - http://www.gnu.org/software/emacs/elisp/html_node/Documentation-Tips.html
[2] - http://cedet.sourceforge.net/checkdoc.shtml