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 = new Pod::Coverage 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
package
private an array of regexen which define what symbols are regarded as private (and so need not be documented) defaults to /^_/, /^import$/, /^DESTROY/, /^AUTOLOAD/, /^bootstrap$/.
private
also_private items are appended to the private list
also_private
If pod_from is supplied, that file is parsed for the documentation, rather than using Pod::Find
pod_from
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.
$object-
undef
why_unrated
Returns a list of uncovered routines, will implicitly call coverage if it's not already been called.
Note, private 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 identifiers will be skipped.
naked
In order to allow internals debugging, while allowing the optimiser to do it's 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.
Pod::Coverage
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
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
Added Pod::Coverage::CountParents which counts the Pod sections from higher in the inheritance tree (it walks @ISA).
Refactored _get_pods into its own method to allow this.
_get_pods
Fixed a typo in mstevens' name (oopsie)
Added examples/script-covered based on an email exchange.
examples/script-covered
Modified the import form so that if given one argument it's assumed to be the package. From a suggestion by Mark Fowler.
Changed tracing to use optimisable constants.
Added why_unrated.
Paul Johnson beat me to making Pod::Coverage a Devel::Cover plugin, so that's one less thing in the TODO section.
Ran the code through perltidy, made some of the changes it suggested.
Worked over the parsing of the also_private flag to give it more consistent semantics
Assimilated examples/pod_cover.t from Tels
examples/pod_cover.t
Implemented _CvGV based upon code from Robin Houston. This removes the dependency on Devel::Peek (the CPAN version of Devel::Peek doesn't supply CvGV). This also happily makes the module work on with perl 5.005_03.
Fixed a bug in the import routine which was preventing the use form of derived classes. Reports a module is unrated if coverage returns undef.
Added Pod::Checker::Overloader.
First cut at making inheritance easy. Pod::Checker::ExportOnly isa Pod::Checker which only checks what Exporter is allowed to hand out.
Fixed up bad docs from the 0.05 release.
Used Pod::Find to deal with alternative locations for pod files. Introduced pod_from. Merged some patches from Schwern. Added in covered. Assimilated examples/check_installed as contributed by Kirrily "Skud" Robert <skud@cpan.org>. Copes with multple functions documented by one section. Added uncovered as a synonym for naked.
examples/check_installed
Just 0.03 with a correctly generated README file
Applied a patch from Dave Rolsky (barely 6 hours after release of 0.02) to improve scanning of pod markers.
Fixed up the import form. Removed dependency on List::Util. Added naked method. Exposed private configuration.
As #london.pm invaded Brighton, people taked about documentation standards. mstevens scribbled something down, richardc coded it, the rest is ponies.
Test::More, Devel::Cover
Richard Clamp <richardc@unixbeard.net>
Michael Stevens <mstevens@etla.org>
Copyright (c) 2001 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.
To install Pod::Coverage::Extractor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Coverage::Extractor
CPAN shell
perl -MCPAN -e shell install Pod::Coverage::Extractor
For more information on module installation, please visit the detailed CPAN module installation guide.