xenial (3) Perl::Critic::Policy::Documentation::RequirePodSections.3pm.gz

NAME

       Perl::Critic::Policy::Documentation::RequirePodSections - Organize your POD into the customary sections.

AFFILIATION

       This Policy is part of the core Perl::Critic distribution.

DESCRIPTION

       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.

DEFAULTS

       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

CONFIGURATION

       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

LIMITATIONS

       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 "=head1", the "__END__" (if any), or the "__DATA__" (if any), whichever comes first.

AUTHOR

       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT

       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

perl v5.20.2                                       2Perl::Critic::Policy::Documentation::RequirePodSections(3pm)