[BioRuby] bioruby documentation

[jan aerts (RI)]

Good morning again.

If I understand correctly, the general feeling is that the class-level
docs should have a bit of standardized bit in them (a description, an
example) and that method-level docs should not be too elaborate if
that's not necessary. How about (given Toshiaki's comment of "[making]
clear what should be documented at least, especially for the non-native
developers") for _non-trivial_ methods giving a description, an example,
and the type of thing it returns? (These could or could not be nicely
put under separate headers; con: can look bloated, pro: speeds up
browsing if you want to know what a method returns). I think the
Bio::Sequence::Common#window_search is a nice example: tells you what
it's meant to do, gives an example, and says what it returns.

So what do you think of the following:
* standardized parts for class-level docs: description, example, and if
necessary: relationship to other classes
* for complex methods: use Bio::Sequence::Common#window_search as an
example (with or without little title thingies)
* for simple methods: use simple methods of the Rails
ActionController::Base as an example: just a one-line description

As rdoc takes care of listing arguments to a class: is there a way to
let it show automatically if an argument is mandatory or not?

jan.


> -----Original Message-----
> From: Ryan Raaum [mailto:rlr215 at nyu.edu] 
> Sent: 06 March 2006 18:46
> To: jan aerts (RI)
> Cc: bioruby at open-bio.org
> Subject: Re: [BioRuby] bioruby documentation
> 
> Hi all (again!),
> 
> Putting the formalization into a more concrete perspective, compare:
> 
> an example from the bioperl docs:
> http://doc.bioperl.org/releases/bioperl-1.0.1/Bio/Tools/SeqStats.html
> 
> and an example from the Ruby on Rails docs:
> http://api.rubyonrails.org/classes/ActionController/Base.html
> 
> The bioperl example is very formalized, so it is true that 
> nothing is left out.  However, it doesn't read very well and 
> most of the method documentation ends up being highly 
> repetitive:  (To caricature... :)
> 
> Title   : do_something
> Usage   : Object.do_something
> Function: does something
> Returns : something
> Args    : precursor to something
> 
> Whereas (in my mind), the rails documentation reads very 
> well, simple methods are simply documented, complex methods 
> are documented in detail.  If the arguments are absent or 
> obvious, don't talk about them; if the arguments are tricky, 
> do talk about them. And so on.  No one really *wants* to 
> document, and if documenting is annoying (= overly 
> formalized), no one will.
> 
> I think a consistent, relatively formalized overview is good, 
> but that overly formalized method and attribute documentation 
> guidelines ultimately mean that little to no documentation 
> will get done because it's too annoying (in most real-world 
> open source projects).
> 
> Best,
> 
> Ryan
> 
> On Mar 6, 2006, at 1:21 PM, jan aerts (RI) wrote:
> 
> > Ryan,
> >
> > Nice piece of doc. I completely agree that the level of 
> formalization 
> > is entirely open to discussion. And I completely understand your 
> > concerns. But on the other hand, a formalized list of things to be 
> > described can, in my opinion, _help_ developers document 
> their code, 
> > rather than it would keep them from doing that. You can see it as a 
> > checklist of things to document. In your piece of code, you 
> describe 
> > several aspects of the subseq method, but for every new 
> method you'd 
> > describe, you'd need to have this list of things in the 
> back of your 
> > head that you have to mention ("did I mention that it 
> returns itself?"
> > "did I mention what the defaults for the arguments are", 
> ...). If we 
> > would have this list accessible on the wiki for any 
> developer, he/she 
> > could copy it into their code and fill it in like a checklist. I 
> > suspect that would make things much easier on the developer (but 
> > that's my own view, of course).
> >
> > You're right that rdoc already takes care of argument lists, but it 
> > only lists them, instead of describing them. And in many 
> instances, a 
> > bioruby user would have to know what the arguments actually are 
> > (including their defaults) without going into the code. Ergo:
> > arguments should be documented.
> >
> > What do you think?
> > jan
> >
> >
> > -----Original Message-----
> > From: Ryan Raaum [mailto:rlr215 at nyu.edu]
> > Sent: Mon 3/6/2006 3:14 PM
> > To: jan aerts (RI)
> > Cc: bioruby at open-bio.org
> > Subject: Re: [BioRuby] bioruby documentation
> >
> >
> > 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
> >>>
> >>>
> >
> >
> 
>