Documentation Inheritance

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?

Comment on Documentation Inheritance

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	[reply]
Re: Documentation Inheritance by osfameron (Hermit) on Dec 13, 2004 at 08:47 UTC
It might be worth looking at Mark Overmeer's OODoc - I've not used it myself, but I seem to remember it does what you want. Cheerio! Osfameron http://osfameron.perlmonk.org/chickenman/	[reply]
Re^2: Documentation Inheritance by zentara (Cardinal) on Dec 13, 2004 at 13:36 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	[reply]
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.	[reply]
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.	[reply]
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.	[reply]