[BioRuby] bioruby documentation

[Trevor Wennblom]

jan aerts (RI) wrote:
> (2) Given the effort developers have put into writing the classes, it
> would be nice if bioruby could reach as wide an audience as possible.
> What I believe would help tremendously, is a standardized format for
> documentation. By this I mean that the following information is given
> for each method (sort of like in bioperl documentation):
>     * synopsis
>     * description
>     * function
>     * what it returns
>     * any arguments
>   

Hi Jan,

Thanks for taking the initiative on this important subject!  Coming up 
with a standard for documenting the major classes and modules would be a 
great idea, I've tried my best on the components that I've written so far.

I'm going to agree with Ryan that documenting every method is likely 
overkill.  One of the beauties of Ruby is that one or two line methods 
become commonplace.  Often to read BioPerl code (where they do generally 
have every method formally documented) I strip out the comments since 
they dominate the code to such a degree as to be distracting, and the 
comments are often just there to meet spec but not provide useful 
information.  If we were to require documentation of methods I would say 
that it should only be required for public methods.


> (4) Encapsule the copyright information between '#--' and '#++', as it
> distracts the user from what he/she wants to know. (It _is_ important,
> but not for the average user...)
>   

We're switching to the Ruby license, correct?  Do we even need anything 
beyond "License:: Ruby"?

Thanks again,
Trevor