Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

Inline POD certainly restricts the possible format of your documentation. Win32::TieRegistry's documentation would suck by comparison if I tried to use inline POD for it.

The advantage of inline POD is that you can keep the documentation of the interface close to the definition of the interface. The problems with that are that 1) good POD should contain a lot more than just the documentation of the interface and 2) Perl doesn't let you define an interface other than via its implementation.

So inline POD forces the co-mingling of the implementation and lots of non-interface documentation (like examples, explanations, etc.). This can easily make the implementation fragmented and harder to understand/maintain and make the documentation fragmented and harder to understand/maintain.

Now, if Perl offered interface declarations (like subroutine prototypes in many other languages), then I'd likely co-mingle those into the POD.

But I mostly don't use co-mingled POD because I think it leads to pretty ugly documentation. I like to control the flow of the documentation in hopes of making it easy to understand and also control the flow of the code for the same reason. These goals usually don't lead to the code being in the same order as the POD so I usually don't co-mingle them.

Update: Yes, Perl subroutine declarations, especially of OO methods, only define a name and so are pretty useless. If Perl had "more traditional" subroutine declarations, than changing the interface w/o updating the documentation (where the declaration is co-mingled) should produce an error about mismatched prototypes in order to remind you to update the documentation.

        - tye (but my friends call me "Tye")

In reply to (tye)Re: Inline POD vs. EOF POD by tye
in thread Inline POD vs. EOF POD by lachoy

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
  • 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.
  • Log In?

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

    How do I use this? | Other CB clients
    Other Users?
    Others examining the Monastery: (8)
    As of 2015-10-13 23:45 GMT
    Find Nodes?
      Voting Booth?

      Does Humor Belong in Programming?

      Results (318 votes), past polls