If your perl code is self-documenting, it makes sense to embed it into
POD; so one needs to have a section of the program which is
simultaneously code *and* POD. Perl parser was designed with this
functionality in mind (its parsing rules for recognition of POD are
made slightly different from POD formatters); however, I do not recall
this being mentioned before (tested to run with Perl 5.00466..5.8.2; I
tested perldoc of 5.8.2; do not know how to test with older versions,
but I see no reason why it should not work):
#!perl -wl
use strict;
use Data::Dumper;
=head1 NAME
self-documenting - Try self-documenting code
=head1 SYNOPSIS
perl self-documenting
perldoc self-documenting
=head1 DESCRIPTION
This package defines the following hash:
=cut
my %h = do { # POD starts where statement can start...
=for POD-and-code
=cut
key1 => 'value1',
key2 => 'value2';
=cut # Perl reads this as begin-POD (preceeding ; is needed)
=cut # Thus one =cut is NOT enough...
};
print Dumper \%h;
print 11;
__END__
Hope this helps,
Ilya