Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Pod::Coverage
Checks if the documentation of a module is comprehensive

Pod::Coverage - Checks if the documentation of a module is comprehensive


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, 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 /^_/, /^import$/, /^DESTROY$/, /^AUTOLOAD$/, /^bootstrap$/, /^(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)$/. That last big one covers all the required and optional methods for tie()d objects, as these methods are (hardly) ever called by a user, 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

$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

the Test::More manpage, the Devel::Cover manpage


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 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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy