1Pod::Coverage(3) User Contributed Perl Documentation Pod::Coverage(3)
2
6 Pod::Coverage - Checks if the documentation of a module is
7 comprehensive
8
10 # in the beginnning...
11 perl -MPod::Coverage=Pod::Coverage -e666
12 # all in one invocation
14 use Pod::Coverage package => 'Fishy';
15 # straight OO
17 use Pod::Coverage;
18 my $pc = Pod::Coverage->new(package => 'Pod::Coverage');
19 print "We rock!" if $pc->coverage == 1;
20
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 This module provides a mechanism for determining if the pod for a given
28 module is comprehensive.
29 It expects to find either a "=head(n>1)" or an "=item" block
31 documenting a subroutine.
32 Consider:
34 # an imaginary Foo.pm
35 package Foo;
36 =item foo
38 The foo sub
40 = cut
42 sub foo {}
44 sub bar {}
45 1;
47 __END__
48 In this example "Foo::foo" is covered, but "Foo::bar" is not, so the
50 "Foo" package is only 50% (0.5) covered
51 Methods
53 Pod::Coverage->new(package => $package)
54 Creates a new Pod::Coverage object.
55 "package" the name of the package to analyse
57 "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 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 "also_private" items are appended to the private list
81 "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 If "pod_from" is supplied, that file is parsed for the
87 documentation, rather than using Pod::Find
88 If "nonwhitespace" is supplied, then only POD sections which have
90 non-whitespace characters will count towards being documented.
91 $object->coverage
93 Gives the coverage as a value in the range 0 to 1
94 $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 $object->naked/$object->uncovered
101 Returns a list of uncovered routines, will implicitly call coverage
102 if it's not already been called.
103 Note, private and 'trustme' identifiers will be skipped.
105 $object->covered
107 Returns a list of covered routines, will implicitly call coverage
108 if it's not previously been called.
109 As with "naked", private and 'trustme' identifiers will be skipped.
111 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 Use them like so
118 sub Pod::Coverage::TRACE_ALL () { 1 }
120 use Pod::Coverage;
121 Supported constants are:
123 TRACE_ALL
125 Trace everything.
126 Well that's all there is so far, are you glad you came?
128 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 NOTE Please consider this interface as in a state of flux until this
135 comment goes away.
136 $object->_CvGV($symbol)
138 Return the GV for the coderef supplied. Used by "_get_syms" to
139 identify locally defined code.
140 You probably won't need to override this one.
142 $object->_get_syms($package)
144 return a list of symbols to check for from the specified packahe
145 _get_pods
147 Extract pod markers from the currently active package.
148 Return an arrayref or undef on fail.
150 _private_check($symbol)
152 return true if the symbol should be considered private
153 _trustme_check($symbol)
155 return true if the symbol is a 'trustme' symbol
156
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
163 Widen the rules for identifying documentation
164 Improve the code coverage of the test suite. "Devel::Cover" rocks so
165 hard.
166
168 Test::More, Devel::Cover
169
171 Richard Clamp <richardc@unixbeard.net>
172 Michael Stevens <mstevens@etla.org>
174 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.
181perl v5.38.0 2023-07-21 Pod::Coverage(3)