Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

Documentation Inheritance

by narse (Pilgrim)
on Dec 12, 2004 at 17:17 UTC ( #414241=perlquestion: print w/replies, xml ) Need Help??

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

Hi all. I am looking for a way to inherit perldoc documentation from other packages. I would like objects to inherit pod as well as methods from their superclass. In my case, the most important methods are inherited and I would like the documentation for the subclass to reflect this, however, duplication of comments is unreasonable and will undoubtable lead to stale documentation.

I understand the difficulties resulting from the freedom of style in pod. I would be willing to adopt certain documentation styles to accomplish my goals. I may also be willing to run a script that copies comments from one pm to another althought this seems sloppy.

Does anyone have any suggestions?

Replies are listed 'Best First'.
Re: Documentation Inheritance
by kvale (Monsignor) on Dec 12, 2004 at 17:32 UTC
    The way this is usually done is to provide a link to the superclass documentation. I suppose one could use this link as a kind of an include statement in your postprocessing to pull in sections from the other perldocs (after you have parsed them), but as you say, it seems a bit inelegant. I would stick with the hypertext links; they are much easier to code and most people are fine with using links..

    -Mark

Re: Documentation Inheritance
by osfameron (Hermit) on Dec 13, 2004 at 08:47 UTC
      Thanks to chickenman , my faith in javascript has been restored Thank you Chickenman!! :-)

      I'm not really a human, but I play one on earth. flash japh
Re: Documentation Inheritance
by simonm (Vicar) on Dec 12, 2004 at 19:10 UTC
    I'd agree with kvale; the standard solution to this problem is to cross-reference the appropriate sections of the other documents with L<...> tags.

    If you do want to build a summary POD that includes information from other sources, I think you'll need a pre-processing step with a separate script or template to build it.

    I would suggest approaching this by writing your documentation as a template using one of the existing templating tools, like Template::Toolkit or my own Text::MicroMason. The template can include the local POD content and template directives to grep out the relevant bits of the other source files.

Re: Documentation Inheritance
by jplindstrom (Monsignor) on Dec 12, 2004 at 22:35 UTC
    I actually had the same idea in 2001 (I just looked at the file dates), and I wrote a Pod::Class::Flattened which never left my computer. I was somewhat of a n00b at the time and I don't think it was very solid, but it worked for my problem at that time.

    If you /msg me I can let you have the source. I probably won't be able to answer questions about it in any coherent way though :)

    /J

    Update:

    This idea with the inherited api documentation is great BTW, I got inspired by reading Bertrand Meyer's Eiffel book.

Re: Documentation Inheritance
by dimar (Curate) on Dec 12, 2004 at 19:38 UTC

    One feature (IMHO) that would be a real treat to have in perl is something similar to Python Docstrings. Even though this is not a feature of perl, you may be able to get some ideas for modularizing your documentation by seeing how they do it in python-land. "Borrowing" conventions from them may be a way to gain some ideas. Just my 2 cents.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://414241]
Approved by kvale
Front-paged by Old_Gray_Bear
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (1)
As of 2021-10-27 02:54 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My first memorable Perl project was:







    Results (91 votes). Check out past polls.

    Notices?