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.
 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 p
      • 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 interspersers" and "POD separatists", respectly!

        I tend to intersperse POD liberally with my code. For each method or function, I dedicate a third level heading and a description (a paragraph or two, maybe a list or two). These, in turn, are roughly grouped into categories under second level POD headings, if possible. Often it _is_ possible, since Perl is quite flexible in subroutine definition placement.

        While many programmers find it hard to scan and read the code in this case, I find it both easier and liberating. Easier, because there is not only the code but also the intent of the programmer right in front of my eyes (assuming the documentation is up to date...); liberating, because I can start writing the API documentation before I have written a single line of code, and then just fill in the gaps between paragraphs. It also enforces a high-level structure that wraps the code module into a narrative one can read from start to end -- or jump into using the table of contents.

        However, this is clearly low-level documentation. I often add user documentation at the top of the file in a separate DESCRIPTION or SYNOPSIS section, or just create a separate POD file for those.

        Coming back to the raised issues, POD is a valuable tool for many purposes. I don't think it's stretched too far. Part of the reason why it can be used in so varied cases is its simplicity, and also because it is like a traditional comment on steroids: it can be easily extracted. With POD syntax, one can mark which comments communicate high-level information and which do not.

        With that in mind, I agree with masak: it should be possible to indent POD blocks with arbitrary whitespace. They may not be as visually separated from the code as they are now, though. Doesn't this indicate a change in syntax is required?