NAME

       Perl::Critic::Policy::Documentation::ProhibitLinkToSelf - don't L<> link to own POD

DESCRIPTION

       This policy is part of the "Perl::Critic::Pulp" add-on.  It asks you not to use "L<>"
       markup to refer to a POD document itself.

           =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 low severity and under the "cosmetic"
       theme (see "POLICY THEMES" in Perl::Critic).

       In ordinary text the suggestion is plain "C<>" or similar for one's own module name,

           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.  Not sure if that's a good idea.

           =head1 NAME

           My::Package -- blah

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

           =head1 DESCRIPTION

       It's always possible an "L<>" is right and in fact the "NAME" appearing is wrong.  A
       violation on the "L<>" will at least show there's something fishy in the one or the other.

   Disabling
       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),

           [-Documentation::ProhibitLinkToSelf]

       If you like to almost always put "L<>" on module names, including in the module's own POD,
       then disable this policy.  Maybe an option in the future could allow links to self in
       ordinary text but prohibit in "SEE ALSO".

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

       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/>.

perl v5.32.1                         Perl::Critic::Policy::Documentation::ProhibitLinkToSelf(3pm)