[BioRuby] rdoc specs

[Trevor Wennblom]

On Apr 24, 2007, at 1:55 AM, jan aerts ((RI)) wrote:

> to make sure that at least minimal documentation is provided. It  
> might be a good idea to edit that file instead of the README file  
> and just make a reference to README.DEV in the README file itself.

Yep, your right - I meant to say README.DEV but didn't, oops.

So here's a few questions I could use some input on -

As far as the file-level documentation is concerned, does it really  
need much detail at all?  The purpose seems to be to just say "I'm a  
file with these classes" - the only place people would ever see it is  
if they're looking at it on the left-pane of the RDoc web-view or  
browsing the source.  Should the key purpose be to indicate what kind  
of "things" the file contains?

Also do we even need to have what the filename is in the header?  I'm  
not against it, but it does seem redundant, especially since RDoc  
already adds that in its own headers.

I kind of like the ERB documentation in ruby core as a rough example  
of file-level compared to class-level documentation:
http://ruby-doc.org/core/files/lib/erb_rb.html
http://ruby-doc.org/core/classes/ERB.html

It also seems like we have two styles of "class" and I'm not sure  
what words to use to distinguish them.  There are the primary public- 
API classes that should have extensive documentation with examples  
and use cases (as well as formal arguments and return values), but  
then there are all the little classes that help out the main  
interfaces that don't need nearly as much documentation (but should  
still have documented the formal arguments, etc.).  What should we be  
calling those?  How do we make the formal distinction?