Hiya jonadab,
Here's a quick online POD page link (which I printed off and stuck to my wall as a reference tool).
As for POD coding style, that's something you'll have to develop yourself.
HTH | [reply] [Watch: Dir/Any] |
| [reply] [Watch: Dir/Any] |
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$/
| [reply] [Watch: Dir/Any] [d/l] |
... talk mainly about how to stick one big block of documentation at the top or bottom of the whole file...
That's one way of doing it (or looking at it) I guess, but what's to stop you from adding multiple blocks of POD?
#!/usr/bin/perl -w
use strict;
# codage...
=head1 NAME
doStuff function
=head1 DESCRIPTION
This sub is designed blah de blah blah
and on and on etc ad infinitum
=cut
sub doStuff {
# code for sub
}
# codage...
=head1 NAME
What the next line does
=head1 DESCRIPTION
This line uses some funky techniques I picked
up from PM and does the following...
=cut
# insert incredibly funky bit of perl code here
# carry on coding...
HTH, if not lemme know and I'll try to anser any more q's you have | [reply] [Watch: Dir/Any] [d/l] |
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.
That is exactly the same. You return to code with =cut. An example:
I hate maintaining code that is interrupted by documentation. I prefer updating the code first, documentation later. Otherwise, I'd probably end up putting tests, real code and documentation all in one place. Awful.
Juerd
# { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }
| [reply] [Watch: Dir/Any] [d/l] [select] |