>> [Derek:]
>> If one wanted to spent some time documenting a library or extension
>> (one's
>> own, or someone else's), where would be a good place to look for
>> documentation on RDoc, and any documentation conventions to be
>> followed?
>
> [Dave:]
> For Ruby libraries, you could just have a look at RDoc's README for
> information on how to use it. As for conventions, they'll be coming
> along shortly. I know Gavin's done some work on the standard library,
> but that might have to change a tad if we want to make it work nicely
> with 'ri' in future. (For example, file-level comments are not
> accessible through ri, as files don't have any meaning at that level.)
> Frankly I don't know the details right now: I'm still learning.

The way we approach the standard library is this:
 - file-level comments can be used to describe background (e.g. CGI)
 - class-level comments should give a good overview of class
 - method-level comments are snappy (I've always kept ri in mind)

That's not to say we get it right all the time, but I'll be reviewing
documentation with these in mind.

Derek, the best way to learn some conventions for the standard library is
to look at the existing documentation at http://www.ruby-doc.org/stdlib. 
'cgi', 'drb' and 'net/*' are good.

Gavin