[Biojava-l] Preparation for a 1.1 release?

[Mark Schreiber]

Probably the most useful documentation would be a kind of API
documentation or tutorial type documentation of the type used for the
alphabet / seqeunce API. 

Javadoc comments for each method of a class would be good (and should
probably be required minimum) but if each class had a paragraph or two
discussing how it relates to the rest of the API and an example of how it
might be used may remove the need for spending hours writing detaied
tutorials. Bruce Eckel's book "Thinking in Java" also suggests that any
class can have an embedded main() method that can be used as a kind of a
demo. In many cases the same demo method could be used in most classes of
the API. Main methods need not be limited to only the application level
classes.

Without some introductory API level documentation the Biojava collection
is quite large and intimidating requiring a fair bit of time investment to
get up and running. Probably not so bad for those who "got in in the
ground floor".

By the way I would like to congratulate "the team" on a generally
excellent effort in making such a large collection of classes in such a
short time.

Just my $NZ 0.02 worth.

Mark

On Fri, 8 Dec 2000, Matthew Pocock wrote:

> 
> 
> Mark Schreiber wrote:
> 
> > Hi,
> >
> > I have been keen to get into biojava for a while but I have been largely
> > staying with my own clases due to the lack of documentation on the biojava
> > API. Basically the only way to get into biojava at the moment is tospend
> > hours looking at the java docs and then comparing to the code to see how
> > things actually work (not that they nescessarily work differently from the
> > documentation its just that often the documentation doesn't tell you
> > enough about how they work).
> >
> > Would it be a good idea if all future contributions to biojava be required
> > to meet a standard of documentation?
> >
> 
> Definitely should have better docs. What would you like to see added? What did
> you work out after hours that could have been learned in 5 mins from an
> example?
> 
> Matthew
> 
> >
> > Mark
> >
> 
> 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mark Schreiber			Ph: 64 3 4797875
Rm 218				email mark_s@sanger.otago.ac.nz
Department of Biochemistry	email m.schreiber@clear.net.nz
University of Otago		
PO Box 56
Dunedin
New Zealand
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~