Perl for Perl's Sake: Yet Another Perl Doc Tool

I don't much like POD. Sure, its ok for a quick bit of usage doc on a small script, or even for a little module with just a few methods. But for serious projects, esp. to be delivered to paying customers, POD is pretty weak.

The reason ? Just take a random walk around CPAN and see how many different styles of docs you can find. My guess is it will be nearly equal to the number of modules you look at.

Then there are the myriad variations of POD formatter behavior. A quick survey leads me to believe most aren't valid (just write some POD inside a string literal or heredoc, and see what your favorite formatter does).

My pet peeve is the lame link tag that can't seem to deal with matching text up with a URL. WTF ? HTML has been doing that for over a decade!

POD's weakness is its simplicity. Its a formatting discipline, not a content discipline. The result is random adherence to somewhat arbitrary de jure standards.

About 18 months ago I was in a bit of a quandry as to how to provide usable docs to a paying customer for a fairly large project with lots of packages, and complex concurrency issues. Part of that exersize led to some upgrades for UML::Sequence. Another part was development of a little formatter for a javadoc-ish embedded docs solution. The customer was very pleased with the resulting docs.

Thanks to PPI and Pod;:ProjectDocs, plus a few helper modules, I've managed to get the formatter into CPANable shape, in the form of Pod::Classdoc. The resulting toolset includes

HTML::ListToTree for easily converting HTML nested list hierarchies into AJAXy Javascripted navigation trees.
PPI::HTML::CodeFolder for compressed and codefolded versions of PPI::HTML output, along with some anchors at package and method definitions.
Pod;:Classdoc to format the aforementioned classdoc POD from within a source tree
Pod;:Classdoc::Project to merge all the above, along with the output of Pod::ProjectDocs, into a single set of project documentation.

Here's an example of the result. It was generated using just the following command:

mkprojdocs -f -o ./classdocs -t "Pod::Classdoc" -d "Generate merged pr
+oject documentation" -D Pod-Classdoc-1.01.tar.gz
[download]

(Well, yes, I did have to write the embedded classdocs... but thats sortof the point)

So if you're looking for a better content discpline for those large Perl projects, and POD just ain't cuttin' it, Pod::Classdoc might fit the bill.

Perl Contrarian & SQL fanboy

Comment on Perl for Perl's Sake: Yet Another Perl Doc Tool Download Code

Replies are listed 'Best First'.
Re: Perl for Perl's Sake: Yet Another Perl Doc Tool by EvanCarroll (Chaplain) on Aug 20, 2007 at 00:18 UTC
I agree fully that pod is insufficient for so many things that it is currently being used for. Thanks for raising the issue. My solution would have been different, but I think you've taken a step in the right direction. I hope the next generation of perldoc, has two discrete functions: the first to comment code, the second to provide tutorials, and howtos. I think the code-comments should be reserved largely for notes that help developers -- what is traditionally a "comment" in other language. The latter function should be something that is heavily dependent on community, internet access, and frozen state wiki concepts. Something kind of like a remote repository of texttile documents, that you can pull from, edit and push back to. With cpan being a web interface frontent to it. I'm still thinking about how this should be done, something with XMLRPC, and some VCS voodoo seems to be the way to go. Evan Carroll www.EvanCarroll.com	[reply]
Re: Perl for Perl's Sake: Yet Another Perl Doc Tool by MidLifeXis (Monsignor) on Aug 22, 2007 at 17:42 UTC
While I like the format of this and NaturalDocs, I really don't like that I need to maintain two types of documentation - one for command line output (`perldoc foobratz.pl`), and one for web (or other output format) enabled documentation. It would be nice to have something that you maintain in one location, and that processes into any output (like POD), in a full featured way (nd or this module). This sounds like another good tool. Any ideas on one that allows maintenance of one set of documentation comments? --MidLifeXis	[reply] [d/l]
Re^2: Perl for Perl's Sake: Yet Another Perl Doc Tool by renodino (Curate) on Aug 22, 2007 at 18:45 UTC
Since Pod::Classdoc just uses special POD tags ("=begin/end classdoc") wrapped inside POD sections, presumably its just a matter of writing an appropriate POD filter (plus something - e.g., PPI - to detect the beginning of package/method definitions). OTOH, maybe Lynx would work with the HTML version ? I've not tried it (and frankly am not inclined to). BTW: thanks for the NaturalDocs link, I'd not heard of it before. Perl Contrarian & SQL fanboy	[reply]


Your skill will accomplish what the force of many cannot
	PerlMonks