Decent POD should include a raft of things that don't have a one-to-one correspondence with the code. Typically the only part that corresponds nicely is the method descriptions, so somewhere before that you have to dump the long description, and somewhere after that belongs stuff like bugs, contact info, see also, usage examples, etc. (Assuming this is a package). It's not worth the tradeoff of putting the user documentation for each method (or function) next to the code, to have to put half of the rest of your POD before the first one, and the other half after the last one.

And folding is in the eye of the beholding editor, unless you get to dictate how others view your code, or ensure that they never do (in which case, what do you need POD for anyway?). I've *never* seen code with interspersed POD that wasn't substantially harder to read than it would have been if the POD were all at the end, or better yet in a separate file altogether. And my editor doesn't readily fold stuff, but it sure does split-screen nicely. That's hardly a fancy or new feature, since Emacs has had it for about 25 years now, and it makes it easy to look at 2 different places in the file at once--or even at 2 different files.

In reply to Re^5: [literate programming] How to mix POD with code? And how to fold this? by ssandv
in thread [literate programming] How to mix POD with code? And how to fold this? by LanX

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.