[Bioperl-l] on BP documentation

[Chris Fields]

On Aug 17, 2009, at 8:04 AM, Amir Karger wrote:

>> -----Original Message-----
>> From: Mark A. Jensen [mailto:maj at fortinbras.us]
>>
>> From: "Hilmar Lapp" <hlapp at gmx.net>
>> ...
>>> As for the FASTA example, I can understand - I've heard
>> repeatedly
>>> from people that one of the things that they are missing is
>>> documentation for every SeqIO format we support  (such as
>> GenBank,
>>> UniProt, FASTA, etc) about where to find a particular piece of
>> the
>>> format in the object model.
>>
>> This is the right thread for list lurkers to contribute their betes
>> noires
>> such as this one. I encourage ALL to post these issues and help
>> create
>> our list of action items.
>> MAJ
>
> I wish you the best of luck on this ambitious and crucial project. I
> teach intro Perl classes to biologists and always tell them that  
> Bioperl
> is amazingly useful, but only if you can figure out how to use it. If
> what you want to do isn't in the howtos, you can be in big trouble.
>
> I was trying to remember specific examples of where I've gotten lost,
> and unfortunately can't give any. But I can tell you that often I've  
> run
> into trouble because the particular method I'm looking for is three
> parent classes away from the module I'm actually looking at. The
> deobfuscator helps some, but only for people who know about that. Do  
> you
> think you could automate a tool that would add the following to the
> bottom of each module?
>
> =head2 Inherited methods
>
> =over 4
>
> =item desc
>
> See Bio::Seq::Basic
>
> =back
>
> This would make browsing through the docs on bioperl.org more fun too.
>
> -Amir Karger

For many modules this is already in place, but yes this could be  
improved.

One of the problems I suggest we avoid when doing this is placing  
these interspersed within code.  It has been demonstrated that doing  
so actually slows down the perl interpreter slightly; it has to slog  
through lots of POD to find the code at the compilation step.  This  
occurs only upon on initial compilation, but it is significant enough  
that the overall recommendation by most perl brethren (and in Perl  
Best Practices) has been to place any POD after an __END__ marker.   
This way the compiler doesn't have to look at it at all, but perldoc  
can still find it.

Also, acc to PBP, although the inline POD would seemingly be easier to  
take care of, apparently the opposite is true in most cases (though it  
can come down to styling differences).  Interspersed code is much  
harder to maintain in a consistent state, tends to be choppier, and  
can be laid out in odd ways due to being scattered throughout the file.

I know this can come down to a difference in style, but the arguments  
do make sense enough to me that in Biome I am pushing to have all docs  
after the __END__ marker.  Lincoln already practices this within  
bioperl and Bio::Graphics, and I plan on moving much on my  
documentation similarly within my code in BioPerl.

The additional comments in the PBP chapter "Documentation" are well- 
worth reading if you can get your hands on it.

chris