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 option has two generic values,
module_starter_pbp, and two version-specific values,
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.
language option has a default, unnamed value but also accepts values of
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_US is in how the word "licence" is spelled.
The sections required for modules and programs can be independently customized, overriding any values for
language, by giving values for
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.
This Policy applies to the entire document, but can be disabled for a particular document by a
## no critic (RequirePodSections) annotation anywhere between the beginning of the document and the first POD section containing a
__END__ (if any), or the
__DATA__ (if any), whichever comes first.
Jeffrey Ryan Thalhammer <email@example.com>
Copyright (c) 2006-2011 Imaginative Software Systems. 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