Perl::Critic::Policy::UsermPerl::Critic::Policy::Documentation::PodSpelling(3)Test The Spell CommandNAMEPerl::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 stopword 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-2011 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.14.1Perl::Critic::Policy::Documentation::PodSpelling(3)
