[BioRuby] bioruby documentation

[jan aerts (RI)]

Hi Trevor,

I agree that, if at all, only public methods should be documented. And, as you say, one or two lines of comment become commonplace. However, we have to keep in mind that it's the end-user that is the target for the docs. Myself having used BioPerl a lot, I found the included method-docs almost always sufficient for using them. The fact that some BioPerl developers did not adequately supply information (be it in that formal format) probably means that they would not provide documentation at all if not for that standard.

If the consensus would be _not_ to document the methods, I'll of course go for that. What do the heavy-weights think?
jan.


-----Original Message-----
From: Trevor Wennblom [mailto:trevor at corevx.com]
Sent: Mon 3/6/2006 6:06 PM
To: jan aerts (RI); bioruby at open-bio.org
Subject: Re: [BioRuby] bioruby documentation
 
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