-
-
01 May 2013 13:14:58 UTC
- Distribution: Pod-Coverage
- Module version: 0.23
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (22)
- Testers (23696 / 7 / 0)
- Kwalitee
Bus factor: 0- 14.53% Coverage
- License: unknown
- Activity
24 month- Tools
- Download (12.9KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Devel::Symdump
- Pod::Find
- Pod::Parser
- Test::More
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Pod::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, butFoo::bar
is not, so theFoo
package is only 50% (0.5) coveredMethods
- Pod::Coverage->new(package => $package)
-
Creates a new Pod::Coverage object.
package
the name of the package to analyseprivate
an array of regexen which define what symbols are regarded as private (and so need not be documented) defaults to [ qr/^_/, qr/^(un)?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 | SCALAR )$/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 listtrustme
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 themIf
pod_from
is supplied, that file is parsed for the documentation, rather than using Pod::FindIf
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 returnundef
, to indicate that it was unable to deduce coverage for a package. If this happens you should be able to checkwhy_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 extendPod::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
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.
Module Install Instructions
To install Pod::Coverage, copy and paste the appropriate command in to your terminal.
cpanm Pod::Coverage
perl -MCPAN -e shell install Pod::Coverage
For more information on module installation, please visit the detailed CPAN module installation guide.