Perl::Critic::Policy::Documentation::ProhibitLinkToSelf - don't L<> link to own POD
This policy is part of the Perl::Critic::Pulp addon. It asks you not to use L<> markup to refer to a POD document itself.
Perl::Critic::Pulp
L<>
=head1 NAME My::Package - something =head1 DESCRIPTION L<My::Package> does blah blah ... # bad =head1 SEE ALSO L<My::Package> # bad
The idea is that it doesn't make sense to link to a document from within itself. If rendered as a clickable link then it may suggest there's somewhere else to go to read about the module, when in fact you're already looking at it.
This is only a minor thing though, so this policy is under the cosmetic theme (see "POLICY THEMES" in Perl::Critic) and low priority.
cosmetic
In ordinary text the is plain C<> or similar for one's own module name,
C<>
C<My::Package> does something something ... # ok
In a "SEE ALSO" a link to self in very likely a typo, or too much cut and paste, or at least pretty unnecessary since there's no need to "see also" what you've just read.
If linking to a particular section within one's own document then use L<> with just the section part. This will probably give better looking output from the formatters too,
L<My::Package/SECTION> # bad L</SECTION> # ok
For this policy the name of the POD is picked out of the "=head1 NAME" section, so doesn't depend on the filename or directory where perlcritic is run. In the current code multiple names can be given in man-page style, but not certain yet if that's a good idea.
perlcritic
=head1 NAME My::Package -- blah My::Package::Parser -- and its parser =head1 DESCRIPTION
Of course it's always possible an L<> like is right and it's the "NAME" part which is wrong. A violation on the L<> will at least show there's something fishy in the one or the other.
If you don't care about this then you can always disable ProhibitLinkToSelf from your .perlcriticrc file in the usual way (see "CONFIGURATION" in Perl::Critic),
ProhibitLinkToSelf
[-Documentation::ProhibitLinkToSelf]
Some people may like to more or less always put L<> on module names, including in the module's own POD. For that you may want to disable this policy. Perhaps an option could allow link to self in ordinary link but still rate "SEE ALSO" as a typo or unnecessary.
Perl::Critic::Pulp, Perl::Critic
Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName, Perl::Critic::Policy::Documentation::ProhibitAdjacentLinks
http://user42.tuxfamily.org/perl-critic-pulp/index.html
Copyright 2011, 2012 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/>.
To install Perl::Critic::Pulp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl::Critic::Pulp
CPAN shell
perl -MCPAN -e shell install Perl::Critic::Pulp
For more information on module installation, please visit the detailed CPAN module installation guide.