Speaking of Ruby and documentation, I'd like to put in a suggestion for  document strings. Emacs Lisp and Python both have it, and in both cases I think it is a really good thing and made heavy use of it. It means at run time one can get very specific documentation information.

I leave open where and how this information is tagged. In both Emacs Lisp and Python this is a string that appears after the method "signature". However
it is also possible that something could be done to use the comment before the method definition, the same as rdoc currently uses.

Finally, I'd like to put in a plug for Paul

On Mon, May 5, 2008 at 2:55 AM, Ryan Davis <ryand-ruby <at> zenspider.com> wrote:

On May 4, 2008, at 13:37 , Phil Hagelberg wrote:

"Jeremy McAnally" <jeremymcanally <at> 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]

I guess Phil brings up a good point... emacs lisp doco is a breeze to read.

I don't mind any work making rdoc more consistent, but I'll resist any efforts to make it so damn structured. Do we really need to have an h4 tag for the parameters, options, returns, examples sections??? Let's leave javadoc to the java ppl and do something cleaner and clearer.