Perl::...elling(3pm)

Hey bestie 💖 welcome to Perl::...elling(3pm), from the User Contributed Perl Documentation collection. This is the Perl::Critic::Policy::Documentation::PodSpelling page, and yes, we're doing spelling today. Periodt. ✨

✨ NAME ✨

• Perl::Critic::Policy::Documentation::PodSpelling — Check your spelling.

🫶 AFFILIATION 🫶

This Policy is part of the core Perl::Critic distribution. She's core, bestie. 💅

🌸 DESCRIPTION 🌸

Okay so the vibe check here is documentation. 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. It's giving "external spell checker says no" 💀.

If anything else goes wrong — we can't locate the spell checking program or (gasp!) your module has no POD — then this policy passes. Like, she just vibes through. 🦋

To add exceptions on a module-by-module basis, add stopwords as described in Pod::Spell. Example time:

=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. That's the contract, bestie. 🫡

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. Here's a silly example of 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. Iconic. 👑

💀 NOTES 💀

A spell checking program is not included with Perl::Critic. Not me expecting aspell to come bundled 😭.

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. Detective era 🔍.

🧚 PREREQUISITES 🧚

This policy will disable itself if File::Which is not available. No File::Which, no policy — she's out. 💅

🌈 CREDITS 🌈

Initial development of this policy was supported by a grant from the Perl Foundation. Shoutout to the Perl Foundation, iconic. 🫶

👑 AUTHOR 👑

Chris Dolan <cdolan@cpan.org> — that's the author, bestie.

⭐ COPYRIGHT ⭐

Copyright (c) 2007-2023 Chris Dolan. Many rights reserved. (Yes, many. Not all. Read it and weep, lol.)

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.

---

💖 And that's the footer tea: perl v5.42.0, dated 2024-10-23, on Perl::...elling(3pm). Byeee bestie — go spell-check those PODs! 🫶✨