[Bioperl-l] strand() question

[Jason Stajich]

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.


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