Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
With the "my ($x, $y, $z) = @_" style, I don't have a clean place for those comments, unless I want to break the list on the left across many lines (ick).

Why not just put the type documentation into the embeded programmer documentation above your function? To call your function correctly, others need to know what they can and can't pass to it, and what will happen if they do. In other words, the type information is a valuable part of your function interface documentation.

I embed the documentation for my function interfaces (as well as general 'programmer' documentation), within a special pod section, dedicated to the "programmerdocs" pod translator. When I need to extract the user documentation, the regular pod translator ignores the programmerdocs section. When I need to extract the programmer documentation, I have a twenty line perl script that extracts the 'programmmerdocs' section, and pipes the results of those sections to the standard pod translator.

It's a bit of an abuse of the pod translator concept, but it works, and it keeps the two kinds of embeded documentation separatate, and easy to access. If anyone has a better method for keeping distict forms of documentation separate, I'm open to suggestions. So far, abusing pod has worked for me.

I like extractable function documenation, because it allows a tester to write unit tests for all the functions without reading any of the implementation details. If the code doesn't match the documentation, the coder needs to fix one or both of his code or documentation.

In reply to Re^5: Stupid mistakes I repeatedly make by Anonymous Monk
in thread Stupid mistakes I repeatedly make by brian_d_foy

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, 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 all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others having an uproarious good time at the Monastery: (8)
    As of 2018-04-19 13:58 GMT
    Find Nodes?
      Voting Booth?