Re: Documentation guidlines (Was: 2nd try at date/format.rb & pty.c)

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

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.


mathew