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

    • When I actually wrote a Perl 6 module with POD I found that I actually duplicated the signatures in the POD, because they are just so expressive.

      So I nagged p6l over this duplication (and triggered a huge flame war :/ ), and as a result Damian Conway came up with a way to include parts of the code from within the POD.

      Why am I telling you this here? Because that mechanism will encourage interleaved POD, because it's easier to reference something close by. So the Problem won't go away anytime soon.
      • Interesting, considering in PBP Damian suggests (In Documentation, under 'Contiguity') not to intersperse POD throughout code, for similar reasons already stated here.