Yes, it's another commenting node. But wait! It's constrained to a simple (?) topic which, AFAICT through super search, hasn't been discussed directly before:
Which POD commenting style do you prefer: inline POD or end-of-file POD? (examples of both below)
Personally, I'm ambivalent. (If I weren't, I wouldn't be asking for an opinion, right?)
I like inline POD because it keeps the code and docs closer together. This doesn't ensure that both get updated at the same time, but it makes updating much easier. It also helps comments directly above the subroutine not get out of sync with docs in POD.
I like end-of-file POD because all the code is in one place and the docs in another -- for many people this is easier to read.
I recently posed this question to the OpenInteract developers' mailing list but didn't get much of a response. One comment I got was that editors don't get confused as easily by EOF POD. (Yes, even (X)Emacs/CPerl gets occasionally confused by inline POD.)
If I were writing code just for me, I would use inline POD. However, I'm trying to make it easier for people to get involved with some more complicated and sizeable CPAN modules, and code readability is high on the list of impediments. However, good and consistent docs are also high on that list....
Chris
M-x auto-bs-mode
Inline POD example:
package My::Class; =pod =head1 NAME My::Class -- Does whatever I tell it =head1 SYNOPSIS my $my = My::Class->new(); my $paper = eval { $my->fetch_paper() }; if ( $@ ) { die "Sorry, could not fetch paper because of: $@"; } =head1 DESCRIPTION This class defines a multipurpose, serializable and network transportable object. =head1 METHODS =cut use strict; @My::Class::ISA = (); $My::Class::VERSION = '1.1'; =pod B<new( \%params )> (constructor) Create a new instance of this class. Initialize the object with whatever is in C<\%params>, which are not predefined.</p> Returns: new instance of this class. =cut sub new { my ( $pkg, $params ) = @_; my $class = ref $pkg || $pkg; return bless( $params, $class ); } =pod B<fetch_paper()> Retrieves paper from environment and returns it. Should be wrapped in an C<eval{}> to catch errors. Returns: L<My::Paper> object. =cut sub fetch_paper { my ( $self ) = @_; ... } 1; __END__ =pod =head1 TO DO Other operations should be added: fetch_slippers, eat_homework. =head1 BUGS Ensure that no C<My::Flea> objects are associated with object. =head1 COPYRIGHT Same as Perl. =head1 AUTHORS J. Appleseed <johnny@appleseed.com> =cut
End-of-file POD example:
package My::Class; use strict; @My::Class::ISA = (); $My::Class::VERSION = '1.1'; sub new { my ( $pkg, $params ) = @_; my $class = ref $pkg || $pkg; return bless( $params, $class ); } sub fetch_paper { my ( $self ) = @_; ... } 1; __END__ =pod =head1 NAME My::Class -- Does whatever I tell it =head1 SYNOPSIS my $my = My::Class->new(); my $paper = eval { $my->fetch_paper() }; if ( $@ ) { die "Sorry, could not fetch paper because of: $@"; } =head1 DESCRIPTION This class defines a multipurpose, serializable and network transportable object. =head1 METHODS B<new( \%params )> (constructor) Create a new instance of this class. Initialize the object with whatever is in C<\%params>, which are not predefined.</p> Returns: new instance of this class. B<fetch_paper()> Retrieves paper from environment and returns it. Should be wrapped in an C<eval{}> to catch errors. Returns: L<My::Paper> object. =head1 TO DO Other operations should be added: fetch_slippers, eat_homework. =head1 BUGS Ensure that no C<My::Flea> objects are associated with object. =head1 COPYRIGHT Same as Perl. =head1 AUTHORS J. Appleseed <johnny@appleseed.com> =cut