[BioRuby] rdoc specs
trevor at corevx.com
Tue Apr 24 17:56:27 UTC 2007
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:
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?
More information about the BioRuby