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/^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)$/x,
70 qr/^( MODIFY | FETCH )_( REF | SCALAR | ARRAY | HASH | CODE
71 |
72 GLOB | FORMAT | IO)_ATTRIBUTES$/x,
73 qr/^CLONE(_SKIP)?$/, ]
74 This should cover all the usual magical methods for tie()d objects,
76 attributes, generally all the methods that are typically not called
77 by a user, but instead being used internally by perl.
78 "also_private" items are appended to the private list
80 "trustme" an array of regexen which define what symbols you just
82 want us to assume are properly documented even if we can't find any
83 docs for them
84 If "pod_from" is supplied, that file is parsed for the
86 documentation, rather than using Pod::Find
87 If "nonwhitespace" is supplied, then only POD sections which have
89 non-whitespace characters will count towards being documented.
90 $object->coverage
92 Gives the coverage as a value in the range 0 to 1
93 $object->why_unrated
95 "$object->coverage" may return "undef", to indicate that it was
96 unable to deduce coverage for a package. If this happens you
97 should be able to check "why_unrated" to get a useful excuse.
98 $object->naked/$object->uncovered
100 Returns a list of uncovered routines, will implicitly call coverage
101 if it's not already been called.
102 Note, private and 'trustme' identifiers will be skipped.
104 $object->covered
106 Returns a list of covered routines, will implicitly call coverage
107 if it's not previously been called.
108 As with "naked", private and 'trustme' identifiers will be skipped.
110 Debugging support
112 In order to allow internals debugging, while allowing the optimiser to
113 do its thang, "Pod::Coverage" uses constant subs to define how it
114 traces.
115 Use them like so
117 sub Pod::Coverage::TRACE_ALL () { 1 }
119 use Pod::Coverage;
120 Supported constants are:
122 TRACE_ALL
124 Trace everything.
125 Well that's all there is so far, are you glad you came?
127 Inheritance interface
129 These abstract methods while functional in "Pod::Coverage" may make
130 your life easier if you want to extend "Pod::Coverage" to fit your
131 house style more closely.
132 NOTE Please consider this interface as in a state of flux until this
134 comment goes away.
135 $object->_CvGV($symbol)
137 Return the GV for the coderef supplied. Used by "_get_syms" to
138 identify locally defined code.
139 You probably won't need to override this one.
141 $object->_get_syms($package)
143 return a list of symbols to check for from the specified packahe
144 _get_pods
146 Extract pod markers from the currently active package.
147 Return an arrayref or undef on fail.
149 _private_check($symbol)
151 return true if the symbol should be considered private
152 _trustme_check($symbol)
154 return true if the symbol is a 'trustme' symbol
155
157 Due to the method used to identify documented subroutines
158 "Pod::Coverage" may completely miss your house style and declare your
159 code undocumented. Patches and/or failing tests welcome.
160
162 Widen the rules for identifying documentation
163 Improve the code coverage of the test suite. "Devel::Cover" rocks so
164 hard.
165
167 Test::More, Devel::Cover
168
170 Richard Clamp <richardc@unixbeard.net>
171 Michael Stevens <mstevens@etla.org>
173 some contributions from David Cantrell <david@cantrell.org.uk>
175
177 Copyright (c) 2001, 2003, 2004, 2006, 2007, 2009 Richard Clamp, Michael
178 Stevens. All rights reserved. This program is free software; you can
179 redistribute it and/or modify it under the same terms as Perl itself.
180perl v5.12.0 2010-05-04 Pod::Coverage(3)