Perl::...kToSelf(3pm)

📦
version 100 · 7 versions
, in ubuntu resolute, ubuntu stonking

💖 Perl::Critic::Policy::Documentation::ProhibitLinkToSelf 💖

ok so bestie, this is a page from the User Contributed Perl Documentation for Perl::...kToSelf(3pm) (yes the real name is Perl::Critic::Policy::Documentation::ProhibitLinkToSelf, the header just got shy and truncated itself, we love her anyway) 🎀

✨ NAME ✨

Perl::Critic::Policy::Documentation::ProhibitLinkToSelf — literally just: don't L<> link to your own POD. that's it. that's the whole job. 💅

🌸 DESCRIPTION 🌸

so this policy is part of the Perl::Critic::Pulp add-on, and it is politely asking you, hands on your shoulders, eye contact, kindly: please do not use L<> markup to refer to a POD document itself. stop linking to yourself. we see you. 🙈

like, imagine this:

=head1 NAME

My::Package - something

=head1 DESCRIPTION

L<My::Package> does blah blah ...     # bad

=head1 SEE ALSO

L<My::Package>                        # bad

both of those # bad comments are not a vibe, bestie. 😭

the idea here (and it's a good one) is that it genuinely doesn't make sense to link to a document from inside itself. if a formatter renders it as a clickable link, it kinda implies there's somewhere else to go read about the module… when you are, right now, literally already looking at it. it's giving "turn around, we're already here." 💀

but ngl, this is only a minor thing. so the policy is low severity and lives under the cosmetic theme (peep "POLICY THEMES" in Perl::Critic if you want the full tea).

in ordinary running text, what you actually want is plain C<> or something like it for your own module name:

C<My::Package> does something something ...   # ok

slay. ✅

and in a "SEE ALSO" section? a link to self is very likely a typo, or too much cut and paste (we've all been there, no judgement 🫶), or at the very least pretty unnecessary — because why would you need to "see also" the exact thing you just finished reading? that's the whole page. you already saw it. 🦋

if you do want to link to a particular section within your own document, then use L<> with just the section part. bonus: the formatters will probably give you better looking output too,

L<My::Package/SECTION>      # bad

L</SECTION>                 # ok

not me leaving the /SECTION on like that, embarrassing 😭

for this policy, the name of the POD is picked out of the "=head1 NAME" section — so it does not depend on the filename or the directory where "perlcritic" is run. iconic, honestly. in the current code, multiple names can be given in man-page style. (the author says: "Not sure if that's a good idea." — and honestly? same energy.) 👑

=head1 NAME

My::Package -- blah

My::Package::Parser -- and its parser

=head1 DESCRIPTION

it's always possible that an "L<>" is right and in fact the "NAME" appearing is wrong. in that case a violation on the "L<>" will at least show you there's something fishy in one or the other. vibe check failed, but productively. 🌈

🎀 Disabling 🎀

if you don't care about any of this, you can always disable "ProhibitLinkToSelf" from your .perlcriticrc file in the usual way (see "CONFIGURATION" in Perl::Critic),

[-Documentation::ProhibitLinkToSelf]

if you like to almost always put "L<>" on module names — including inside the module's own POD — then yeah, disable this policy, live your truth. 💜 maybe an option in the future could allow links to self in ordinary text but prohibit them in "SEE ALSO". (future feature, not a real one yet, don't come for me.)

🔥 SEE ALSO 🔥

Perl::Critic::Pulp, Perl::Critic

Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName, Perl::Critic::Policy::Documentation::ProhibitAdjacentLinks

🌟 HOME PAGE 🌟

<http://user42.tuxfamily.org/perl-critic-pulp/index.html>

Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019, 2021 Kevin Ryde

Perl-Critic-Pulp is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Perl-Critic-Pulp is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses/>.

and that's the whole page bestie, tysm for reading 💖 this was perl v5.40.1, dated 2025-10-21, and yes the footer truncated the policy name too — she's shy, we love her, mwah 🎀✨

📦 where this page comes from