Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Three things in Perl 6 that aren't so great 3 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.

  • I have to say, I find the whole idea of POD interspersed with code quite loathsome. It appreciate all the reasons why it's a Good Thing (which boils down to keeping the docs as close to the code as possible), but it has so many drawbacks.

    Most notably, it makes it hard to skim through the code when there's big globs of POD getting in the way. If I'm reading the source then it's code I want to concentrate on. If it's the end-user documentation that I want then I'll use perldoc or look at an HTML version

    • I think you've touched upon something that leads to the root of the issue - the fact that there are several different types of documentation that is produced, each with different display needs and different audiences, and possibly different authors.

      Like you said, comments are written by the programmer, for other programmers (including oneself) and are intended to communicate knowledge about the nearby code.

      On the other hand, POD's purpose is a little more loosely defined. POD is usually written by the programmer, usually for the end-user of the code, usually with the purpose of being displayed separately from the code.

      Notice I used the word "usually" a lot there.

      What this suggests to me is that POD's purpose is probably being stretched a little too far. POD seems to suffer from the problem of being a documentation jack-of-all-trades - and master of none.

      • Exactly! POD is indeed used for multiple purposes; some people have even authored books written in POD.

        However, I find the debate between "POD interspersers" and "POD separatists" boils down to only two usages of POD. The first is to document the API, which is a low-level documentation from one programmer to another. The second is to document the program, which is a high-level documentation from the programmer to the user. Incidentally these two use cases follow closely the preferences of "POD interspers

Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.