[BioRuby] bioruby documentation
Trevor Wennblom
trevor at corevx.com
Mon Mar 6 18:06:11 UTC 2006
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
More information about the BioRuby
mailing list