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

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