noble (3) Perl::Critic::Policy::Documentation::PodSpelling.3pm.gz

NAME

       Perl::Critic::Policy::Documentation::PodSpelling - Check your spelling.

AFFILIATION

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

DESCRIPTION

       Did you write the documentation?  Check.

       Did you document all of the public methods?  Check.

       Is your documentation readable?  Hmm...

       Ideally, we'd like Perl::Critic to tell you when your documentation is inadequate.  That's hard to code,
       though.  So, inspired by Test::Spelling, this module checks the spelling of your POD.  It does this by
       pulling the prose out of the code and passing it to an external spell checker.  It skips over words you
       flagged to ignore.  If the spell checker returns any misspelled words, this policy emits a violation.

       If anything else goes wrong -- we can't locate the spell checking program or (gasp!) your module has no
       POD -- then this policy passes.

       To add exceptions on a module-by-module basis, add "stopwords" as described in Pod::Spell.  For example:

           =for stopwords gibbles

           =head1 Gibble::Manip -- manipulate your gibbles

           =cut

CONFIGURATION

       This policy can be configured to tell which spell checker to use or to set a global list of spelling
       exceptions.  To do this, put entries in a .perlcriticrc file like this:

           [Documentation::PodSpelling]
           spell_command = aspell list
           stop_words = gibbles foobar
           stop_words_file = some/path/with/stop/words.txt

       The default spell command is "aspell list" and it is interpreted as a shell command.  We parse the
       individual arguments via Text::ParseWords so feel free to use quotes around your arguments.  If the
       executable path is an absolute file name, it is used as-is.  If it is a relative file name, we employ
       File::Which to convert it to an absolute path via the "PATH" environment variable.  As described in
       Pod::Spell and Test::Spelling, the spell checker must accept text on STDIN and print misspelled words one
       per line on STDOUT.

       You can specify global stop words via the "stop_words" and "stop_words_file" options.  The former is
       simply split up on whitespace.  The latter is looked at line by line, with anything after an octothorp
       ("#") removed and then leading and trailing whitespace removed.  Silly example valid file contents:

           # It's a comment!

           foo
           arglbargl    # Some other comment.
           bar

       The values from "stop_words" and "stop_words_file" are merged together into a single list of exemptions.

NOTES

       A spell checking program is not included with Perl::Critic.

       The results of failures for this policy can be confusing when aspell complains about words containing
       punctuation such as hyphens and apostrophes.  In this situation aspell will often only emit part of the
       word that it thinks is misspelled.  For example, if you ask aspell to check "foobie-bletch", the output
       only complains about "foobie".  Unfortunately, you'll have to look through your POD to figure out what
       the real word that aspell is complaining about is.  One thing to try is looking at the output of "perl
       -MPod::Spell -e 'print Pod::Spell->new()->parse_from_file("lib/Your/Module.pm")'" to see what is actually
       being checked for spelling.

PREREQUISITES

       This policy will disable itself if File::Which is not available.

CREDITS

       Initial development of this policy was supported by a grant from the Perl Foundation.

AUTHOR

       Chris Dolan <cdolan@cpan.org>

COPYRIGHT

       Copyright (c) 2007-2023 Chris Dolan.  Many 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.36.0                                       2023-10-Perl::Critic::Policy::Documentation::PodSpelling(3pm)