[BioRuby] bioruby documentation

[jan aerts (RI)]

Hi Ryan,

(First of all: I think you sent this message to me alone, instead of the
bioruby mailing list....)

Glad to get the documentation discussion started again... The "as a way
of thorougly understanding the use and structure of the classes" sound
familiar...

What do you think of using a standardized or (sound ugly:) formal
format? Does your documentation include some of the
synopsis/description/function/what it returns/arguments things? Do you
think it is useful/feasible to put them in that format?

Thanks,
jan.

> -----Original Message-----
> From: Ryan Raaum [mailto:rlr215 at nyu.edu] 
> Sent: 06 March 2006 14:41
> To: jan aerts (RI)
> Subject: Re: [BioRuby] bioruby documentation
> 
> Good Morning All,
> 
> I've had similar toughts to Jan, and am a couple methods away 
> from completely documenting Bio::Sequence::* .  I was hoping 
> to send that in to Toshiaki later today.  I haven't yet 
> written a synopsis or description for them, mainly because I 
> was using the process of documenting all the methods as a way 
> of thoroughly understanding the use and structure of the 
> classes.  If the documentation I've currently written is seen 
> as reasonable and accepted, I would then add the overview 
> documentation for those classes and files.
> 
> Is there somewhere we can note which parts different people 
> are working on documenting, so as to avoid any duplication of effort?
> 
> Best!
> 
> -Ryan
> 
> On Mar 6, 2006, at 9:21 AM, jan aerts (RI) wrote:
> 
> > Hi all,
> >
> > Given the posts about bioruby documentation in the last few 
> months, my 
> > own experiences with bioruby and a bit of encouragement 
> from Toshiaki, 
> > I'd like to commence documenting bioruby classes (in CVS) 
> that are not 
> > documented yet, and to standardize the documentation format 
> for those 
> > that already have documentation.
> >
> > Documentation would take the form of rdoc, so that it would be 
> > browsable via the www.bioruby.org/rdoc website.
> >
> > Some guidelines that I would like to use in the documentation:
> > (1) Each class should have a description and synopsis. If 
> there is a 
> > unit test at the bottom, this can easily be tweaked into a 
> synopsis. 
> > If such a unit test is available, 'documentating' would 
> mean (at least 
> > in the first round) 'tweaking and copying the unit test in 
> a comment 
> > in front of the class'. Alternatively, unit tests and documentation 
> > could be combined into one (as Ara and Pjotr discussed), 
> but I'm not 
> > experienced enough in ruby yet to do this in a simple, 
> transparent way.
> > (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
> > (3) It should be made clear to the user if a class should be used 
> > directly, or if it just supports other classes (e.g.
> > Bio::Sequence::Format). Additional important info would be 
> interaction 
> > with other classes (e.g. "how does the sequence class interact with 
> > the embl class?"). Original module writers have an 
> important role in 
> > describing this context.
> > (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...)
> >
> >
> > Example of class documentation (from sequence.rb):
> > # = DESCRIPTION
> > # The Bio::Sequence class generically describes a nucleic or amino 
> > acid sequence and is a superclass of # Bio::Sequence::NA and 
> > Bio::Sequence::AA. Most methods that can be used on Bio::Sequence 
> > objects are described # in Bio::Sequence::Common, Bio::Sequence::NA 
> > and Bio::Sequence::AA # # If possible, create sequence 
> objects using 
> > the Bio::Sequence::NA or Bio::Sequence::AA classes instead, as the 
> > Bio::Sequence # class will have to guess the type of 
> sequence you're 
> > talking about.
> > #
> > # = SYNOPSIS
> > #   # Create a nucleic or amino acid sequence
> > #   dna = Bio::Sequence::NA.new('atgcatgcATGCATGCAAAA')
> > #   rna = Bio::Sequence::NA.new('augcaugcaugcaugcaaaa')
> > #   aa = Bio::Sequence::AA.new('ACDEFGHIKLMNPQRSTVWYU')
> > #
> > #   # Print it out
> > #   puts dna.to_s
> > #   puts aa.to_s
> > #
> > #   # Get a subsequence, bioinformatics style (first 
> nucleotide is '1')
> > #   puts dna.subseq(2,6)
> > #
> > #   #...more examples from the unit test
> >
> > Example of method documentation (from sequence.rb):
> >   # Usage:
> >   #    my_seq = Bio::Sequence('AGGCACGAT')
> >   #    my_na = my_seq.na
> >   # Function::   Converts the Bio::Sequence object into a
> > Bio::Sequence::NA object
> >   # Returns::    a Bio::Sequence::NA object
> >   # Arguments::  none
> >   def na
> >     @seq = NA.new(@seq)
> >     @moltype = NA
> >   end
> >
> > As the time I can work on this is only limited, expect to 
> see gradual 
> > additions to the cvs repository. Any other people wishing 
> to help out 
> > are greatly welcome!!
> >
> > Of course, I promise not to touch other people's code, unless they 
> > explicitely tell me to.
> >
> > Any thoughts/suggestions on this?
> >
> > Kind regards,
> >
> > Jan Aerts, PhD
> > Bioinformatics Group
> > Roslin Institute
> > Roslin, Scotland, UK
> > +33 131 527 4200
> >
> > ---------The obligatory disclaimer-------- The information 
> contained 
> > in this e-mail (including any attachments) is
> > confidential and is intended for the use of the addressee 
> only.   The
> > opinions expressed within this e-mail (including any 
> attachments) are 
> > the opinions of the sender and do not necessarily 
> constitute those of 
> > Roslin Institute (Edinburgh) ("the Institute") unless specifically 
> > stated by a sender who is duly authorised to do so on behalf of the 
> > Institute.
> >
> > _______________________________________________
> > BioRuby mailing list
> > BioRuby at lists.open-bio.org
> > http://lists.open-bio.org/mailman/listinfo/bioruby
> 
>