Both of these tutorials, nice though they may be, talk
mainly about how to stick one big block of documentation
at the top or bottom of the whole file. For me that
would be a step backwards. I'm MUCH more
interested in documenting each function locally, right
near the top of that function, (usually, right below
the line that pulls @_ into named lexicals) like I
would do with comments. I've been led to believe
this is possible with POD, which is why I asked.
Doing it this way makes it easier to
compare the documentation of what the function does
with the function itself, which makes for easier
maintenance. Yes, I know I can split my window in
Emacs and put the doc in one half and the code in
the other, but a lot of times I like to put two
sections of code in the two halves, and when I start
splitting vertically into three parts, I find that it
puts too much crimp on how many lines I can see at
once. Maybe what I really need is a larger monitor,
but until then, I'd like to keep the docs for each
function together with that function.
$;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.
|