use Perl

• The root problem is interspersing code with POD (Score:1)

  by abw (998)

  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
  • Re:The root problem is interspersing code with POD (Score:1)

    by moritz (8678) on 2009.07.25 3:57 (#69629) Homepage Journal

    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.

    Reply to This

    Parent

    • Re: (Score:1)

      by cjfields (3851)

      Interesting, considering in PBP Damian suggests (In Documentation, under 'Contiguity') not to intersperse POD throughout code, for similar reasons already stated here.