Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Policy::UsermContributedcPerllDocumencumentation::PodSpelling(3)

Test The Spell Command
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	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.24.1		   Perl::Critic::Policy::Documentation::PodSpelling(3)

Test The Spell Command | NAME | AFFILIATION | DESCRIPTION | CONFIGURATION | NOTES | PREREQUISITES | CREDITS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Policy::Documentation::PodSpelling&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help