On Aug 21, 2006, at 10:22 AM, mathew wrote:
Eric Hodel wrote:
Here's a start:
* Documentation wrapped to 80 characters
* Use :: and # for describing methods, . for example code
* C methods must have call-seq
* Include plenty of examples.
Personally, examples are the first thing I look for in documentation.
* Make the first page (the one named after the package/library)
contain an introduction to what the package does, why you should
use it, and links to any relevant standards (e.g. RFCs).
Actually, I was wondering about this. When I patched pty.c, clicking
on the pty link still yielded shl.rb. How can I fix it to reference
the PTY class? Also, where can you place summary information for a C
file. Can you just put it at the top?
I also like to include links to alternative packages or libraries
when appropriate.
* Make sure each page of generated Rdoc either contains useful
information, or at least points the reader at a more appropriate page.
* Don't document the internal behavior of the methods.
The purpose of API documentation is to provide a design contract.
If you specify internal implementation details, we end up with
unrefactorable code. (That's also the problem with undocumented
code, but documenting the internal details is even worse.)
For an example of something supposedly well documented that fails
all of the above guidelines, see 'enumerable'... Perhaps I'll have
a go at that when I return from vacation.
At first I thought the enumerable stuff looked okay, but I see what
you mean about documenting internals. each_cons and each_slice look
okay though right?
mathew
Nice name :)
-Mat
|
