[BioRuby] bioruby documentation

Mon Mar 6 15:14:06 UTC 2006

Hello again everyone!

>
> 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?

I think a reasonable standardization is a good thing, especially at the 
overview level of the class or module or whatever.  Here's an example 
of what I've been writing for method documentation:

(This is for subseq in Bio::Sequence::Common)

   # Returns a new sequence containing the subsequence identified by the 
start
   # and end numbers given as parameters.  *Important:* Biological 
sequence
   # numbering conventions (one-based) rather than ruby's (zero-based) 
numbering
   # conventions are used.
   #
   #   s = Bio::Sequence::Generic.new('atggaatga')
   #   puts s.subseq(1,3)                      #=> "atg"
   #
   # Start defaults to 1 and end defaults to the entire existing string, 
so
   # subseq called without any parameters simply returns a new sequence 
identical
   # to the existing sequence.
   #
   #   puts s.subseq                           #=> "atggaatga"
   #

So, I haven't been writing enormously formal specs - which seem like a 
bit of overkill for most of the methods, and rdoc takes care of the 
basics of argument lists.  Otherwise I note what to expect in return, 
or if the method does or does not modify the current object.  Also if 
there are any things that are dangerous or tricky...  I also give an 
example for all methods.

It seems to me, and this is surely open to discussion, that formalizing 
the individual method descriptions too much makes them enormously 
tedious to write - so much so that very few will ever get written.  
BUT, on the class or module level, I think a certain amount of 
formalization is good, so that the overviews are reasonably consistent.

Best,

-Ryan

>
> 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
>>
>>