Perl::Critic::Policy::Documentation::RequirePodSections - Organize your POD into the customary sections.
This Policy is part of the core Perl::Critic distribution.
This Policy requires your POD to contain certain =head1 sections.
If the file doesn't contain any POD at all, then this Policy does not
apply. Tools like Module::Starter make it really easy to ensure
that every module has the same documentation framework, and they can
save you lots of keystrokes.
Different POD sections are required, depending on whether the file is a library or program (which is determined by the presence or absence of a perl shebang line).
Default Required POD Sections
Perl Libraries Perl Programs
------------------------------------------------------
NAME NAME
VERSION
SYNOPSIS USAGE
DESCRIPTION DESCRIPTION
SUBROUTINES/METHODS REQUIRED ARGUMENTS
OPTIONS
DIAGNOSTICS DIAGNOSTICS
EXIT STATUS
CONFIGURATION AND ENVIRONMENT CONFIGURATION
DEPENDENCIES DEPENDENCIES
INCOMPATIBILITIES INCOMPATIBILITIES
BUGS AND LIMITATIONS BUGS AND LIMITATIONS
AUTHOR AUTHOR
LICENSE AND COPYRIGHT LICENSE AND COPYRIGHT
The default sections above are derived from Damian Conway's Perl
Best Practices book. Since the book has been published, Conway has
released Module::Starter::PBP, which has different names for some
of the sections, and adds some more. Also, the book and module use
Australian spelling, while the authors of this module have previously
used American spelling. To sort this all out, there are a couple of
options that can be used: source and language.
The source option has two generic values, book and
module_starter_pbp, and two version-specific values,
book_first_edition and module_starter_pbp_0_0_3. Currently, the
generic values map to the corresponding version-specific values, but
may change as new versions of the book and module are released, so use
these if you want to keep up with the latest and greatest. If you
want things to remain stable, use the version-specific values.
The language option has a default, unnamed value but also accepts
values of en_AU and en_US. The reason the unnamed value exists
is because the default values for programs don't actually match the
book, even taking spelling into account, i.e. CONFIGURATION instead
of CONFIGURATION AND ENVIRONMENT, the removal of VERSION, and
the addition of EXIT STATUS. To get precisely the sections as
specified in the book, put the following in your .perlcriticrc
file:
[Documentation::RequirePodSections] source = book_first_edition language = en_AU
If you want to use
[Documentation::RequirePodSections] source = module_starter_pbp language = en_US
you will need to modify your ~/.module-starter/PBP/Module.pm template because it is generated using Australian spelling.
Presently, the difference between en_AU and en_US is in how the
word "licence" is spelled.
The sections required for modules and programs can be independently
customized, overriding any values for source and language, by
giving values for script_sections and lib_sections of a string
of pipe-delimited required POD section names. An example of entries
in a .perlcriticrc file:
[Documentation::RequirePodSections] lib_sections = NAME | SYNOPSIS | BUGS AND LIMITATIONS | AUTHOR script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR
Currently, this Policy does not look for the required POD sections
below the =head1 level. Also, it does not require the sections to
appear in any particular order.
Jeffrey Ryan Thalhammer <thaljef@cpan.org>
Copyright (c) 2006-2008 Jeffrey Ryan Thalhammer. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module