1Perl::Critic::Policy::DUosceurPmeeCrnoltn:at:trCiirobinut:ti:ecPd:o:dPPSeoprlelilclDyio:nc:guD(mo3ecpnumtm)aetnitoantion::PodSpelling(3pm)
2
6 Perl::Critic::Policy::Documentation::PodSpelling - Check your spelling.
7
9 This Policy is part of the core Perl::Critic distribution.
10
12 Did you write the documentation? Check.
13 Did you document all of the public methods? Check.
15 Is your documentation readable? Hmm...
17 Ideally, we'd like Perl::Critic to tell you when your documentation is
19 inadequate. That's hard to code, though. So, inspired by
20 Test::Spelling, this module checks the spelling of your POD. It does
21 this by pulling the prose out of the code and passing it to an external
22 spell checker. It skips over words you flagged to ignore. If the
23 spell checker returns any misspelled words, this policy emits a
24 violation.
25 If anything else goes wrong -- we can't locate the spell checking
27 program or (gasp!) your module has no POD -- then this policy passes.
28 To add exceptions on a module-by-module basis, add "stopwords" as
30 described in Pod::Spell. For example:
31 =for stopwords gibbles
33 =head1 Gibble::Manip -- manipulate your gibbles
35 =cut
37
39 This policy can be configured to tell which spell checker to use or to
40 set a global list of spelling exceptions. To do this, put entries in a
41 .perlcriticrc file like this:
42 [Documentation::PodSpelling]
44 spell_command = hunspell -l
45 stop_words = gibbles foobar
46 stop_words_file = some/path/with/stop/words.txt
47 The default spell command is "hunspell -l" and it is interpreted as a
49 shell command. We parse the individual arguments via Text::ParseWords
50 so feel free to use quotes around your arguments. If the executable
51 path is an absolute file name, it is used as-is. If it is a relative
52 file name, we employ File::Which to convert it to an absolute path via
53 the "PATH" environment variable. As described in Pod::Spell and
54 Test::Spelling, the spell checker must accept text on STDIN and print
55 misspelled words one per line on STDOUT.
56 You can specify global stop words via the "stop_words" and
58 "stop_words_file" options. The former is simply split up on
59 whitespace. The latter is looked at line by line, with anything after
60 an octothorp ("#") removed and then leading and trailing whitespace
61 removed. Silly example valid file contents:
62 # It's a comment!
64 foo
66 arglbargl # Some other comment.
67 bar
68 The values from "stop_words" and "stop_words_file" are merged together
70 into a single list of exemptions.
71
73 A spell checking program is not included with Perl::Critic.
74 The results of failures for this policy can be confusing when hunspell
76 complains about words containing punctuation such as hyphens and
77 apostrophes. In this situation hunspell will often only emit part of
78 the word that it thinks is misspelled. For example, if you ask
79 hunspell to check "foobie-bletch", the output only complains about
80 "foobie". Unfortunately, you'll have to look through your POD to
81 figure out what the real word that hunspell is complaining about is.
82 One thing to try is looking at the output of "perl -MPod::Spell -e
83 'print Pod::Spell->new()->parse_from_file("lib/Your/Module.pm")'" to
84 see what is actually being checked for spelling.
85
87 This policy will disable itself if File::Which is not available.
88
90 Initial development of this policy was supported by a grant from the
91 Perl Foundation.
92
94 Chris Dolan <cdolan@cpan.org>
95
97 Copyright (c) 2007-2023 Chris Dolan. Many rights reserved.
98 This program is free software; you can redistribute it and/or modify it
100 under the same terms as Perl itself. The full text of this license can
101 be found in the LICENSE file included with this module
102perl v5.38.0 Perl::Cri2t0i2c3:-:0P9o-l2i5cy::Documentation::PodSpelling(3pm)