1Perl::Critic::Policy::DUosceurPmeeCrnoltn:at:trCiirobinut:ti:ecPd:o:dPPSeoprlelilclDyio:nc:guD(mo3ecpnumtm)aetnitoantion::PodSpelling(3pm)
2
3
4

NAME

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

AFFILIATION

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

DESCRIPTION

12       Did you write the documentation?  Check.
13
14       Did you document all of the public methods?  Check.
15
16       Is your documentation readable?  Hmm...
17
18       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
26       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
29       To add exceptions on a module-by-module basis, add "stopwords" as
30       described in Pod::Spell.  For example:
31
32           =for stopwords gibbles
33
34           =head1 Gibble::Manip -- manipulate your gibbles
35
36           =cut
37

CONFIGURATION

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
43           [Documentation::PodSpelling]
44           spell_command = hunspell -l
45           stop_words = gibbles foobar
46           stop_words_file = some/path/with/stop/words.txt
47
48       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
57       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
63           # It's a comment!
64
65           foo
66           arglbargl    # Some other comment.
67           bar
68
69       The values from "stop_words" and "stop_words_file" are merged together
70       into a single list of exemptions.
71

NOTES

73       A spell checking program is not included with Perl::Critic.
74
75       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

PREREQUISITES

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

CREDITS

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

AUTHOR

94       Chris Dolan <cdolan@cpan.org>
95
97       Copyright (c) 2007-2023 Chris Dolan.  Many rights reserved.
98
99       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
102
103
104
105perl v5.38.0             Perl::Cri2t0i2c3:-:0P9o-l2i5cy::Documentation::PodSpelling(3pm)
Impressum