Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW

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

by renodino (Curate)
on Aug 19, 2007 at 01:37 UTC ( #633549=CUFP: print w/replies, xml ) Need Help??

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

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

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


      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

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: CUFP [id://633549]
Approved by BrowserUk
Front-paged by BrowserUk
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (4)
As of 2018-05-23 15:26 GMT
Find Nodes?
    Voting Booth?