I prefer to have most of my documentation at the end of the module, after the __END__. The one fly in this ointment is maintaining the list of functions and the calling information, and brief descriptions, which I prefer to keep just above the functions. For example, if one has to put the module description at the top of the code file, one will tend to write less documentation, if only to not have to scroll through it to get to the start of the "real code". Also, while it's nice to have a short description of what a function does and its arguments, I find there are times when I want longer notes, but not at the head of the function (again for the same reason "you have to scroll through it to get to the code"). Beginning users of a module would be happy if there were documentation at the end (per function), while the maintainers of the module would be happier if there were minimal docs intermixed with the code (well, at least _this_ maintainer would).

The point I'm making is it's nice if the POD and code can be somewhat decoupled in terms of order for a variety of reasons. Another way to put it is documentation and code are different things, that while often go together (for code maintenance), they also tend to get in the way once one knows what one is doing.

Are there any tools that help maintain PODs using this style (auto-copy functions to POD __END__ FUNCTION section)? My thought is that since POD is so simple, the approach is to have some Auto-POD maintainer tools, that do some simple things. Perhaps, for example, they will automatically generate function "calling signatures" from the existing code (i.e. like javadoc, which will give the function signature, but only augment it if you add, for example, argument descriptions).

Note, I've gone through some of the CPAN example modules and I find the intermixing approach to produce (in my opinion) fairly ugly code.

In reply to POD using __END__ with function comments by zerohero

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.