Pod::Coverage(3) User Contributed Perl Documentation Pod::Coverage(3)NAMEPod::Coverage - Checks if the documentation of a module is
comprehensive
SYNOPSIS
# in the beginnning...
perl -MPod::Coverage=Pod::Coverage -e666
# all in one invocation
use Pod::Coverage package => 'Fishy';
# straight OO
use Pod::Coverage;
my $pc = Pod::Coverage->new(package => 'Pod::Coverage');
print "We rock!" if $pc->coverage == 1;
DESCRIPTION
Developers hate writing documentation. They'd hate it even more if
their computer tattled on them, but maybe they'll be even more thankful
in the long run. Even if not, perlmodstyle tells you to, so you must
obey.
This module provides a mechanism for determining if the pod for a given
module is comprehensive.
It expects to find either a "=head(n>1)" or an "=item" block
documenting a subroutine.
Consider:
# an imaginary Foo.pm
package Foo;
=item foo
The foo sub
= cut
sub foo {}
sub bar {}
1;
__END__
In this example "Foo::foo" is covered, but "Foo::bar" is not, so the
"Foo" package is only 50% (0.5) covered
Methods
Pod::Coverage->new(package => $package)
Creates a new Pod::Coverage object.
"package" the name of the package to analyse
"private" an array of regexen which define what symbols are
regarded as private (and so need not be documented) defaults to [
qr/^_/, qr/^import$/, qr/^DESTROY$/, qr/^AUTOLOAD$/,
qr/^bootstrap$/,
qr/^(TIE( SCALAR | ARRAY | HASH | HANDLE ) |
FETCH | STORE | UNTIE | FETCHSIZE | STORESIZE |
POP | PUSH | SHIFT | UNSHIFT | SPLICE | DELETE |
EXISTS | EXTEND | CLEAR | FIRSTKEY | NEXTKEY | PRINT |
PRINTF |
WRITE | READLINE | GETC | READ | CLOSE | BINMODE |
OPEN |
EOF | FILENO | SEEK | TELL)$/x,
qr/^( MODIFY | FETCH )_( REF | SCALAR | ARRAY | HASH | CODE
|
GLOB | FORMAT | IO)_ATTRIBUTES$/x,
qr/^CLONE(_SKIP)?$/, ]
This should cover all the usual magical methods for tie()d objects,
attributes, generally all the methods that are typically not called
by a user, but instead being used internally by perl.
"also_private" items are appended to the private list
"trustme" an array of regexen which define what symbols you just
want us to assume are properly documented even if we can't find any
docs for them
If "pod_from" is supplied, that file is parsed for the
documentation, rather than using Pod::Find
If "nonwhitespace" is supplied, then only POD sections which have
non-whitespace characters will count towards being documented.
$object->coverage
Gives the coverage as a value in the range 0 to 1
$object->why_unrated
"$object->coverage" may return "undef", to indicate that it was
unable to deduce coverage for a package. If this happens you
should be able to check "why_unrated" to get a useful excuse.
$object->naked/$object->uncovered
Returns a list of uncovered routines, will implicitly call coverage
if it's not already been called.
Note, private and 'trustme' identifiers will be skipped.
$object->covered
Returns a list of covered routines, will implicitly call coverage
if it's not previously been called.
As with "naked", private and 'trustme' identifiers will be skipped.
Debugging support
In order to allow internals debugging, while allowing the optimiser to
do its thang, "Pod::Coverage" uses constant subs to define how it
traces.
Use them like so
sub Pod::Coverage::TRACE_ALL () { 1 }
use Pod::Coverage;
Supported constants are:
TRACE_ALL
Trace everything.
Well that's all there is so far, are you glad you came?
Inheritance interface
These abstract methods while functional in "Pod::Coverage" may make
your life easier if you want to extend "Pod::Coverage" to fit your
house style more closely.
NOTE Please consider this interface as in a state of flux until this
comment goes away.
$object->_CvGV($symbol)
Return the GV for the coderef supplied. Used by "_get_syms" to
identify locally defined code.
You probably won't need to override this one.
$object->_get_syms($package)
return a list of symbols to check for from the specified packahe
_get_pods
Extract pod markers from the currently active package.
Return an arrayref or undef on fail.
_private_check($symbol)
return true if the symbol should be considered private
_trustme_check($symbol)
return true if the symbol is a 'trustme' symbol
BUGS
Due to the method used to identify documented subroutines
"Pod::Coverage" may completely miss your house style and declare your
code undocumented. Patches and/or failing tests welcome.
TODO
Widen the rules for identifying documentation
Improve the code coverage of the test suite. "Devel::Cover" rocks so
hard.
SEE ALSO
Test::More, Devel::Cover
AUTHORS
Richard Clamp <richardc@unixbeard.net>
Michael Stevens <mstevens@etla.org>
some contributions from David Cantrell <david@cantrell.org.uk>
COPYRIGHT
Copyright (c) 2001, 2003, 2004, 2006, 2007, 2009 Richard Clamp, Michael
Stevens. All rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.
perl v5.10.1 2010-12-13 Pod::Coverage(3)
