Previously, I've had POD at the end of the file, with a comment block before each subroutine ... straight out of Perl Best Practices pg 141:

 #######################################################
 # Usage:
 # Purpose:
 # Returns:
 # Parameters:
 # Throws:
 # Comments:
 # See Also:

[download]

I'm starting with with a new team, and would like to break up the POD so POD for a subroutine appears right before the code. Hard enough documenting a routine once, why do it twice?

( And frankly, in the long run, I would love to see the "introductory comment block" become part of the code, so the declaration of the routine is extracted from the comments. Slightly more verbose, but easier to read, with room for comments ... and with the potential for including pre-conditions, post-conditions, and more.)

I've tried setting up an item list, where the name of each subroutine is an item, with below it an item list for Usage, Purpose, etc, and a third-level item list for the parameters. I don't like it ... it takes up WAAY too much space in the file, and somewhat too much space in the output display. I think a great routine is 25 lines or less, an acceptable routine is 50 lines or less, and anything longer is a warning flag. Documentation that wastes more screen real estate than the code is a problem ... if it was actually detailed, necessary documentation, it would be different, but it's boilerplate.

Raw POD ... 

=head1 SUBROUTINES/METHODS

=over

=item subroutine_xyz()

=over

=item Usage

my $retval = Module::subroutine_xyz( $arg );

=item Purpose

Do something in some manner;

=item Returns

Useful information about the return value;

=item Parameters

=over

=item $arg - some information which varies the operation of the subrou
+tine;

=back

=back

=cut

[download]

The first C<=over> is still open, to be continued at the next subroutine declaration.

Formatted output ... 

SUBROUTINES/METHODS
       subroutine_xyz()
           Usage
               my $retval = Module::subroutine_xyz( $arg );

           Purpose
               Do something in some manner;

           Returns
               Useful information about the return value;

           Parameters
               $arg - some information which varies the operation of t
+he
               subroutine;

[download]

I COULD just use a preformated text block, just like the original comment block. That would eliminate the duplication, but like HTML vs CSS, it loses information about what components ARE, leaving only how they should be presented.

Has anyone found a succint but informative way to inline POD?

( Love that word 'succint' .. it's so ... succint! )

Tom

--
TTTATCGGTCGTTATATAGATGTTTGCA

In reply to Inline POD formatting by TomDLux

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.