Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
I very rarely use "inline" POD. I'd say never, but since I write Japhs, I rather not say never. For serious code, I *always* use EOF POD.

I've mainly two reasons for that. A theoretical one, and a practical one.

Let's start with a practical one. Ever tried figuring out what a module is exactly doing? Ever tried that with modules that use inline POD? It's like eating soup with loads of hair in it - you can't quickly see what is code and what is POD, especially if the POD uses code blocks! It becomes harder to find the functions.

But the theoretical one is more serious. POD is for writing *user* documentation. That's why pod2man is run. And user documentation describes how you use a program, or a function. Not how it's implemented, unless that's relevant to the usuage. Regardless whether it's a module or a standalone function. Look at your systems manual pages, be them from section 1, 2 or 3. They talk about usuage, not implementation. Furthermore, the best way of describing how to use a command or function is very seldom done in the same order as your code is. Do you think the "ls" command has to code for dealing with the various options in alphabetical order? Or do you think the options shouldn't be described in alphabetical order, but in the order the programmer just happens to group them?

I use block comments to explain the implementation, and POD to explain the usuage. And IMO, if you use only POD, you either have lousy manual pages, or your code is very lousy documented.

-- Abigail


In reply to Re: Inline POD vs. EOF POD by Abigail
in thread Inline POD vs. EOF POD by lachoy

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!
  • 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, 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, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            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.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others musing on the Monastery: (12)
    As of 2014-12-26 08:55 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      Is guessing a good strategy for surviving in the IT business?





      Results (168 votes), past polls