1Pod::Coverage(3)      User Contributed Perl Documentation     Pod::Coverage(3)
2
3
4

NAME

6       Pod::Coverage - Checks if the documentation of a module is
7       comprehensive
8

SYNOPSIS

10         # in the beginnning...
11         perl -MPod::Coverage=Pod::Coverage -e666
12
13         # all in one invocation
14         use Pod::Coverage package => 'Fishy';
15
16         # straight OO
17         use Pod::Coverage;
18         my $pc = Pod::Coverage->new(package => 'Pod::Coverage');
19         print "We rock!" if $pc->coverage == 1;
20

DESCRIPTION

22       Developers hate writing documentation.  They'd hate it even more if
23       their computer tattled on them, but maybe they'll be even more thankful
24       in the long run.  Even if not, perlmodstyle tells you to, so you must
25       obey.
26
27       This module provides a mechanism for determining if the pod for a given
28       module is comprehensive.
29
30       It expects to find either a "=head(n>1)" or an "=item" block
31       documenting a subroutine.
32
33       Consider:
34        # an imaginary Foo.pm
35        package Foo;
36
37        =item foo
38
39        The foo sub
40
41        = cut
42
43        sub foo {}
44        sub bar {}
45
46        1;
47        __END__
48
49       In this example "Foo::foo" is covered, but "Foo::bar" is not, so the
50       "Foo" package is only 50% (0.5) covered
51
52   Methods
53       Pod::Coverage->new(package => $package)
54           Creates a new Pod::Coverage object.
55
56           "package" the name of the package to analyse
57
58           "private" an array of regexen which define what symbols are
59           regarded as private (and so need not be documented) defaults to [
60           qr/^_/, qr/^(un)?import$/, qr/^DESTROY$/, qr/^AUTOLOAD$/,
61           qr/^bootstrap$/,
62                   qr/^(TIE( SCALAR | ARRAY | HASH | HANDLE ) |
63                        FETCH | STORE | UNTIE | FETCHSIZE | STORESIZE |
64                        POP | PUSH | SHIFT | UNSHIFT | SPLICE | DELETE |
65                        EXISTS | EXTEND | CLEAR | FIRSTKEY | NEXTKEY | PRINT |
66           PRINTF |
67                        WRITE | READLINE | GETC | READ | CLOSE | BINMODE |
68           OPEN |
69                        EOF | FILENO | SEEK | TELL | SCALAR )$/x,
70                   qr/^( MODIFY | FETCH )_( REF | SCALAR | ARRAY | HASH | CODE
71           |
72                                            GLOB | FORMAT | IO
73           )_ATTRIBUTES$/x,
74                   qr/^CLONE(_SKIP)?$/, ]
75
76           This should cover all the usual magical methods for tie()d objects,
77           attributes, generally all the methods that are typically not called
78           by a user, but instead being used internally by perl.
79
80           "also_private" items are appended to the private list
81
82           "trustme" an array of regexen which define what symbols you just
83           want us to assume are properly documented even if we can't find any
84           docs for them
85
86           If "pod_from" is supplied, that file is parsed for the
87           documentation, rather than using Pod::Find
88
89           If "nonwhitespace" is supplied, then only POD sections which have
90           non-whitespace characters will count towards being documented.
91
92       $object->coverage
93           Gives the coverage as a value in the range 0 to 1
94
95       $object->why_unrated
96           "$object->coverage" may return "undef", to indicate that it was
97           unable to deduce coverage for a package.  If this happens you
98           should be able to check "why_unrated" to get a useful excuse.
99
100       $object->naked/$object->uncovered
101           Returns a list of uncovered routines, will implicitly call coverage
102           if it's not already been called.
103
104           Note, private and 'trustme' identifiers will be skipped.
105
106       $object->covered
107           Returns a list of covered routines, will implicitly call coverage
108           if it's not previously been called.
109
110           As with "naked", private and 'trustme' identifiers will be skipped.
111
112   Debugging support
113       In order to allow internals debugging, while allowing the optimiser to
114       do its thang, "Pod::Coverage" uses constant subs to define how it
115       traces.
116
117       Use them like so
118
119        sub Pod::Coverage::TRACE_ALL () { 1 }
120        use Pod::Coverage;
121
122       Supported constants are:
123
124       TRACE_ALL
125           Trace everything.
126
127           Well that's all there is so far, are you glad you came?
128
129   Inheritance interface
130       These abstract methods while functional in "Pod::Coverage" may make
131       your life easier if you want to extend "Pod::Coverage" to fit your
132       house style more closely.
133
134       NOTE Please consider this interface as in a state of flux until this
135       comment goes away.
136
137       $object->_CvGV($symbol)
138           Return the GV for the coderef supplied.  Used by "_get_syms" to
139           identify locally defined code.
140
141           You probably won't need to override this one.
142
143       $object->_get_syms($package)
144           return a list of symbols to check for from the specified packahe
145
146       _get_pods
147           Extract pod markers from the currently active package.
148
149           Return an arrayref or undef on fail.
150
151       _private_check($symbol)
152           return true if the symbol should be considered private
153
154       _trustme_check($symbol)
155           return true if the symbol is a 'trustme' symbol
156

BUGS

158       Due to the method used to identify documented subroutines
159       "Pod::Coverage" may completely miss your house style and declare your
160       code undocumented.  Patches and/or failing tests welcome.
161

TODO

163       Widen the rules for identifying documentation
164       Improve the code coverage of the test suite.  "Devel::Cover" rocks so
165       hard.
166

SEE ALSO

168       Test::More, Devel::Cover
169

AUTHORS

171       Richard Clamp <richardc@unixbeard.net>
172
173       Michael Stevens <mstevens@etla.org>
174
175       some contributions from David Cantrell <david@cantrell.org.uk>
176
178       Copyright (c) 2001, 2003, 2004, 2006, 2007, 2009 Richard Clamp, Michael
179       Stevens. All rights reserved.  This program is free software; you can
180       redistribute it and/or modify it under the same terms as Perl itself.
181
182
183
184perl v5.38.0                      2023-07-21                  Pod::Coverage(3)
Impressum