Pod::Coverage - Checks if the documentation of a module is comprehensive
# 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;
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
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.
Gives the coverage as a value in the range 0 to 1
$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.
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.
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.
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 everything.
Well that's all there is so far, are you glad you came?
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.
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.
return a list of symbols to check for from the specified packahe
Extract pod markers from the currently active package.
Return an arrayref or undef on fail.
return true if the symbol should be considered private
return true if the symbol is a 'trustme' symbol
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.
Devel::Cover rocks so hard.
Richard Clamp <richardc@unixbeard.net>
Michael Stevens <mstevens@etla.org>
some contributions from David Cantrell <david@cantrell.org.uk>
Copyright (c) 2001, 2003, 2004, 2006, 2007 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.