rvosa has asked for the wisdom of the Perl Monks concerning the following question:

Is there some way to include, in the perldoc of a module, the documentation for any parents it inherits from (say, up to a certain level)?

Replies are listed 'Best First'.
Re: Introspective POD
by tlm (Prior) on Aug 11, 2005 at 01:59 UTC

    (I hope I'm not totally misunderstanding your question.) The standard practice, in my experience, is a suitable mention in the "SEE ALSO" section of the docs. Relatively low tech, I agree, but probably the only approach that is general enough to be useful.

    the lowliest monk

[reply]
      I'm sceptical about the effictiveness of the SEE ALSO section: i) it has to be hand-maintained, so probably lagging behind development ii) it's usually at the bottom of the POD - many readers will tune out before that.

      I think my question is more general: can a module manipulate its POD, i.e.: 
      =item TITLE

ref $self - frobnication library version $VERSION

=cut

      [download]
      I'm interested in the (hypothetical) ability of interpolating variables (for example from @ISA), so that the documentation doesn't go stale.
[reply]
[d/l]
Re: Introspective POD
by osunderdog (Deacon) on Aug 11, 2005 at 01:58 UTC

    I've never heard of such a feature in pod. I know that you can reference other modules, which in html will equate to a anchor, but not actually include them in the documentation for a module.

    Still Unemployed!

[reply]
Re: Introspective POD
by Your Mother (Archbishop) on Aug 11, 2005 at 01:59 UTC

    L<Parent::Module> :)

[reply]
Re: Introspective POD
by salva (Canon) on Aug 11, 2005 at 08:10 UTC
    no... though you could use an external preprocessor to do so, and then add some rules to your Makefile.PL (or similar) to have pod files automatically build.
[reply]
Re: Introspective POD
by jplindstrom (Monsignor) on Aug 11, 2005 at 15:48 UTC
    I wanted this five years ago and hacked something together which you may find useful.

    It's probably fragile, incomplete, YMMV, etc. and I haven't touched it in like forever. But if you can find a use for it... please, go ahead :)

    /J

[reply]
      Ah, will have a look at that - cheers. It'd be nice if there was some dynamic way to do this, eh... like a switch for the perldoc script to move up the inheritance tree up to a predefined level, running pod2usage on the parents or something and feeding that to the pager, appended to the current module's pod.
[reply]
        running pod2usage on the parents

        Eh... I don't quite understand what you mean by that, IIRC pod2usage is used to generate a script's documentation from POD. Would you care to elaborate?

        /J

[reply]
Re: Introspective POD
by tinita (Parson) on Aug 12, 2005 at 15:04 UTC
    just for fun: 
    inherit(<<'=cut');
=head2 INHERITANCE

=over 4

=item L<Class::DBI>

blah...

=item L<Other::Module>

=back

=cut

sub inherit {
  while($_[0] =~ m/=item L<([\w:]+)>/g) {
    eval "use base $1";
  }
}

    [download]

    update: this has als the positive side effect that you first document and then actually use it. your docs will always be up-to-date =)

[reply]
[d/l]

Back to Seekers of Perl Wisdom