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:
package My::Module;
use strict;
our $VERSION = '1.00';
=head1 NAME
My::Module - An example module
=head1 SYNOPSIS
use My::Module;
my $object = My::Module->new();
print $object->as_string;
=head1 DESCRIPTION
This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.
=head2 Methods
=over 12
=item C<new>
Returns a new My::Module object.
=cut
sub new {
...
}
=item C<as_string>
Returns a stringified representation of
the object. This is mainly for debugging
purposes.
=cut
sub as_string {
...
}
=back
=head1 AUTHOR
Juerd - <http://juerd.nl/>
=head1 SEE ALSO
L<perlpod>, L<perlpodspec>
=cut
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' }
