[BioRuby] bioruby documentation

[jan aerts (RI)]

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.