The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

ELLIOTJS / Perl-Critic-1.101_001 / lib / Perl / Critic / Policy / Documentation / RequirePodAtEnd.pm 

            

              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
—
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

              
##############################################################################
#      $URL: http://perlcritic.tigris.org/svn/perlcritic/branches/Perl-Critic-PPI-1.204/lib/Perl/Critic/Policy/Documentation/RequirePodAtEnd.pm $
#     $Date: 2009-07-21 08:50:56 -0700 (Tue, 21 Jul 2009) $
#   $Author: clonezone $
# $Revision: 3404 $
##############################################################################
package Perl::Critic::Policy::Documentation::RequirePodAtEnd;
use 5.006001;
use strict;
use warnings;
use Readonly;
use List::Util qw(first);
use Perl::Critic::Utils qw{ :severities };
use base 'Perl::Critic::Policy';
our $VERSION = '1.101_001';
#-----------------------------------------------------------------------------
Readonly::Scalar my $POD_RX => qr{\A = (?: for|begin|end ) }xms;
Readonly::Scalar my $DESC => q{POD before __END__};
Readonly::Scalar my $EXPL => [139, 140];
#-----------------------------------------------------------------------------
sub supported_parameters { return ()                      }
sub default_severity     { return $SEVERITY_LOWEST        }
sub default_themes       { return qw( core cosmetic pbp ) }
sub applies_to           { return 'PPI::Document'         }
#-----------------------------------------------------------------------------
sub violates {
    my ( $self, $elem, $doc ) = @_;
    # No POD means no violation
    my $pods_ref = $doc->find('PPI::Token::Pod');
    return if !$pods_ref;
    # Look for first POD tag that isn't =for, =begin, or =end
    my $pod = first { $_ !~ $POD_RX} @{ $pods_ref };
    return if !$pod;
    my $end = $doc->find_first('PPI::Statement::End');
    if ($end) {  # No __END__ means definite violation
        my $pod_loc = $pod->location();
        my $end_loc = $end->location();
        if ( $pod_loc->[0] > $end_loc->[0] ) {
            # POD is after __END__, or relative position couldn't be determined
            return;
        }
    }
    return $self->violation( $DESC, $EXPL, $pod );
}
1;
__END__
#-----------------------------------------------------------------------------
=pod
=head1 NAME
Perl::Critic::Policy::Documentation::RequirePodAtEnd - All POD should be after C<__END__>.
=head1 AFFILIATION
This Policy is part of the core L<Perl::Critic|Perl::Critic>
distribution.
=head1 DESCRIPTION
Perl stops processing code when it sees an C<__END__> statement.  So,
to save processing time, it's faster to put documentation after the
C<__END__>.  Also, writing all the POD in one place usually leads to a
more cohesive document, rather than being forced to follow the layout
of your code.  This policy issues violations if any POD is found
before an C<__END__>.
=head1 CONFIGURATION
This Policy is not configurable except for the standard options.
=head1 NOTES
Some folks like to use C<=for>, and C<=begin>, and C<=end> tags to
create block comments in-line with their code.  Since those tags
aren't usually part of the documentation, this Policy does allows them
to appear before the C<__END__> statement.
    =begin comments
    frobulate()
    Accepts:  A list of things to frobulate
    Returns:  True if succesful
    =end comments
    sub frobulate { ... }
=head1 AUTHOR
Chris Dolan <cdolan@cpan.org>
=head1 COPYRIGHT
Copyright (c) 2006-2009 Chris Dolan.
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
=cut
# Local Variables:
#   mode: cperl
#   cperl-indent-level: 4
#   fill-column: 78
#   indent-tabs-mode: nil
#   c-indentation-style: bsd
# End:
# ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :