I prefer not to surround optional argument with brackets (or any other stuff that is typical of unix man pages) because those have real meanings in Perl. Likewise, I don't really like the pseudocode argument style of "perldoc -f" (i.e. all caps), though that's at least a sort of reference standard.

I prefer to use actual perl structures, named in a way that indicates what they should contain, and then explain them in the actual Pod description. E.g.

=head2 validate

  $is_valid = validate( \@args );

C<validate()> takes a reference to an array of arguments...

[download]

But I'll echo what the others said -- consistency is the most important thing. You'll never get everyone to agree on a form to use, but as long as you're internally consistent, you'll minimize confusion.

-xdg

Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

In reply to Re: POD conventions by xdg
in thread POD conventions by eff_i_g

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.