1Pod::Coverage(3) User Contributed Perl Documentation Pod::Coverage(3)
2
6 Pod::Coverage - Checks if the documentation of a module is comprehen‐
7 sive
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 document‐
31 ing 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)
55 Creates a new Pod::Coverage object.
56 "package" the name of the package to analyse
58 "private" an array of regexen which define what symbols are
60 regarded as private (and so need not be documented) defaults to [
61 qr/^_/, qr/^import$/, qr/^DESTROY$/, qr/^AUTOLOAD$/, qr/^boot‐
62 strap$/,
63 qr/^(TIE( SCALAR ⎪ ARRAY ⎪ HASH ⎪ HANDLE ) ⎪
64 FETCH ⎪ STORE ⎪ UNTIE ⎪ FETCHSIZE ⎪ STORESIZE ⎪
65 POP ⎪ PUSH ⎪ SHIFT ⎪ UNSHIFT ⎪ SPLICE ⎪ DELETE ⎪
66 EXISTS ⎪ EXTEND ⎪ CLEAR ⎪ FIRSTKEY ⎪ NEXTKEY ⎪ PRINT ⎪
67 PRINTF ⎪
68 WRITE ⎪ READLINE ⎪ GETC ⎪ READ ⎪ CLOSE ⎪ BINMODE ⎪
69 OPEN ⎪
70 EOF ⎪ FILENO ⎪ SEEK ⎪ TELL)$/x,
71 qr/^( MODIFY ⎪ FETCH )_( REF ⎪ SCALAR ⎪ ARRAY ⎪ HASH ⎪ CODE
72 ⎪
73 GLOB ⎪ FORMAT ⎪ IO)_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 documenta‐
87 tion, 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
115 do its thang, "Pod::Coverage" uses constant subs to define how it
116 traces.
117 Use them like so
119 sub Pod::Coverage::TRACE_ALL () { 1 }
121 use Pod::Coverage;
122 Supported constants are:
124 TRACE_ALL
126 Trace everything.
127 Well that's all there is so far, are you glad you came?
129 Inheritance interface
131 These abstract methods while functional in "Pod::Coverage" may make
133 your life easier if you want to extend "Pod::Coverage" to fit your
134 house style more closely.
135 NOTE Please consider this interface as in a state of flux until this
137 comment goes away.
138 $object->_CvGV($symbol)
140 Return the GV for the coderef supplied. Used by "_get_syms" to
141 identify locally defined code.
142 You probably won't need to override this one.
144 $object->_get_syms($package)
146 return a list of symbols to check for from the specified packahe
147 _get_pods
149 Extract pod markers from the currently active package.
150 Return an arrayref or undef on fail.
152 _private_check($symbol)
154 return true if the symbol should be considered private
155 _trustme_check($symbol)
157 return true if the symbol is a 'trustme' symbol
158
160 Due to the method used to identify documented subroutines "Pod::Cover‐
161 age" may completely miss your house style and declare your code undocu‐
162 mented. Patches and/or failing tests welcome.
163
165 Widen the rules for identifying documentation
166 Improve the code coverage of the test suite. "Devel::Cover" rocks so
167 hard.
168
170 Test::More, Devel::Cover
171
173 Richard Clamp <richardc@unixbeard.net>
174 Michael Stevens <mstevens@etla.org>
176 some contributions from David Cantrell <david@cantrell.org.uk>
178
180 Copyright (c) 2001, 2003, 2004, 2006 Richard Clamp, Michael Stevens.
181 All rights reserved. This program is free software; you can redis‐
182 tribute it and/or modify it under the same terms as Perl itself.
183perl v5.8.8 2006-08-09 Pod::Coverage(3)