I've seen various options for where to place POD:

I've yet to see the POD at the start of the module but I guess that someone, somewhere, has done that!

For a module I am going to publish on CPAN, I put the POD at the end of the file. I figure that the current version of the module will be 'finished' before it gets uploaded to CPAN.

I assume that a separate POD file is only really helpful for large modules that have several packages that need to be covered by one POD file.

But, for one project, I have a module of helper functions - this is a private module, not something I will publish. The module deals with things I either want to access in different places or that it makes sense to take out of the main scripts. Currently, this file has comments to document the methods, which is OK for a short module. But it's now exceeded 700 lines with a couple of dozen methods, and finding my way around it is becoming frustrating and time-consuming.

I have started to create POD for this module to make it easier for me to find the method and syntax I need when I add some new functionality or update existing functionality.

Because the module is never really 'finished' and gets added to whenever I need a new method, it seems sensible to add the POD next to each method. But I am sure there is more to it than this...am I opening myself up to future problems if I spread the POD through the module and document each method next to that method's code?

Where do you place your POD, and why do you do it that way?

In reply to Where to place POD by Bod

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.