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$/
[download]

... 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...
[download]

HTH, if not lemme know and I'll try to anser any more q's you have

=head1 DESCRIPTION

  This sub is designed blah de blah blah
  and on and on etc ad infinitum

=cut
[download]

That is bad POD style. It's like putting something like this on the monastery:

DESCRIPTION This sub is designed blah de blah blah and on and on etc ad infinitum [download]

Indented paragraphs are verbatim and appear as they are, in a monospaced font. Don't do that unless it is code or you're using ASCII for lay-out.

Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

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:

Read more... (922 Bytes)

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' }

=cut

sub new {
    ...
}
=item C<as_string>
[download]

Ah. I think that was the thing I needed to see, really. Though in my case it may be more like this...

sub authbox {
  my ($input, $callback) = @_;
=item C<authbox>
  authbox ($input, $callback);

  Returns two items.  The first is a string containing a hunk of xhtml
  suitable for inclusion wherever a div can legally be put (e.g.,
  inside a table cell or a paragraph).  If the user is not logged in,
  the box offers login options.  If the user is logged in, it offers a
  logout link.  $input should be a hashref containing any form input
  with keys starting with 'AUTH_'.  $callback should be a closure
  that, if passed a user id, returns a string containing a suitable
  greeting; this string will appear in the authbox.

  The second item in the returned list is the cookie string that
  should be passed to the browser, if any.
=cut
  # Rest of code for function goes here.
}
[download]

Currently I have roughly that form, pretty consistently, but with comments instead of POD. I want to convert it to POD. Unfortunately, I seem to be finding that the version of cperl-mode I have may not support POD properly. update:Yes it does; there was something wrong with my POD.

---

$;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/
[download]

I hate maintaining code that is interrupted by documentation. I prefer updating the code first, documentation later.

If I do that, I end up with incorrect or obsolete documentation. I specifically like to see the ($foo, $bar, $baz) = @_; right above the documentation of the function's arguments, so that if I add any other optional args I see the mismatch and update the docs.

---

$;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/
[download]