[Bioperl-l] strand() question

[Steve Chervitz]

On Tuesday, Jun 10, 2003, at 11:55 US/Pacific, Jason Stajich wrote:

> On Tue, 10 Jun 2003, Steve Chervitz wrote:
>
>> The documentation in GenericHit incorrectly refers you to see
>> SearchUtils. It should instead point you at the interface module which
>> GenericHit implements: Bio::Search::Hit::HitI::strand(). Here's a link
>> to the corresponding HTML version for this method:
>> http://doc.bioperl.org/releases/bioperl-1.2/Bio/Search/Hit/
>> HitI.html#POD25
>>
>> I fixed this and similar documentation bugs in GenericHit on the main
>> trunk.
>>
>> This brings up the issue of what to do with method documentation in an
>> interface module and corresponding implementation modules. The 
>> approach
>> I've been favoring is to refer to the interface documentation from the
>> implementing module and include only implementation-specific docs in
>> the implementing module's method POD.
>>
>> The alternative approach is to cut-and-paste the method POD from the
>> interface into the impl, but this leads to redundancy and
>> synchronization problems and more maintenance work.
>
> yes but people can't seem to figure out the object hierarchy so I've 
> been
> pretty explicitly cutting and pasting where appropriate.  I hate it 
> but we
> definitely had a lot of people unable to understand where the ->query 
> and
> ->hit methods came from for HSPs because they are defined in
> Bio::SeqFeature::SimilarityPair.

I agree it is more convenient to have all of the methods docs in place. 
It makes it easier when using perldoc or when reading source code in an 
editor. Since these are probably the most common ways to read the docs, 
it makes sense to cater to them. It hurts, but I guess I can follow 
suit until a better solution comes along (Perl 6?).

When you do cut and paste docs, I like how you have included a note 
indicating which methods come from another module. In GenericHSP for 
example:

=head2 Inherited from Bio::SeqFeature::SimilarityPair

These methods come from Bio::SeqFeature::SimilarityPair

=head2 query
...
=head2 hit
...

This will help the poor soul who has to ensure the docs remain in sync 
(has this been an issue for you or anyone else yet?).

Steve

>
>>
>> It would be nice to maintain documentation in a single location and
>> simply refer to it. The HTML links would solve the problem nicely... 
>> if
>> they worked. The POD syntax I've been using doesn't seem to work when
>> the HTML docs are generated. Here's an example:
>>
>> =head2 strand
>>
>> See documentation in
>> L<Bio::Search::Hit::HitI::strand()|Bio::Search::Hit::HitI>
>>
>> =cut
>>
>> I'm not that familiar with Pdoc, but it seems like this sort of thing
>> should be possible. Anyone have any tips?
>>
>
> I'm not sure if Raphael is still working on Pdoc, we probably ought to
> reevaluate what is and is not working wrt to documentation and 
> establish a
> standard.  The devs are generating the POD at least - but we perhaps
> aren't providing the most intuitive interface to this documentation for
> the users.
>
> BTW the daily auto-generation of the Pdoc may have been interrupted
> with all the server migration behind the scenes at OBF.  Will have to 
> take
> a look when there is time.
>
> -jason
>
>
>> Steve
>>
>> On Tuesday, Jun 10, 2003, at 04:41 US/Pacific, Brian Osborne wrote:
>>
>>> Annette,
>>>
>>> Check out the SearchIO HOWTO, it might answer your questions:
>>>
>>> http://bioperl.org/HOWTOs/html/SearchIO.html
>>>
>>> If not there will be someone on the list how can provide further
>>> clarification.
>>>
>>> Brian O.
>>>
>>> -----Original Message-----
>>> From: bioperl-l-bounces at portal.open-bio.org
>>> [mailto:bioperl-l-bounces at portal.open-bio.org]On Behalf Of hackstam
>>> Sent: Monday, June 09, 2003 3:03 PM
>>> To: Bioperl-l at portal.open-bio.org
>>> Subject: [Bioperl-l] strand() question
>>>
>>> Sorry if this is not the right place to ask this question
>>> but I am having problems locating the documentation on the
>>> strand function in Bio::Search::Hit::GenericHit.  Could
>>> someone please tell me what are the output values and there
>>> meaning?  Thanks in advance for any help.
>>> Annette
>>> _______________________________________________
>>> Bioperl-l mailing list
>>> Bioperl-l at portal.open-bio.org
>>> http://portal.open-bio.org/mailman/listinfo/bioperl-l
>>>
>>>
>>> _______________________________________________
>>> Bioperl-l mailing list
>>> Bioperl-l at portal.open-bio.org
>>> http://portal.open-bio.org/mailman/listinfo/bioperl-l
>>>
>>
>> _______________________________________________
>> Bioperl-l mailing list
>> Bioperl-l at portal.open-bio.org
>> http://portal.open-bio.org/mailman/listinfo/bioperl-l
>>
>
> --
> Jason Stajich
> Duke University
> jason at cgt.mc.duke.edu
>