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

SYNOPSIS
      # 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;

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 =head2 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$/.

        "also_private" items are appended to the private list

        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->naked/$object->uncovered
        Returns a list of uncovered routines, will implicitly call coverage
        if it's not already been called.

        Note, private 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 identifiers will be skipped.

  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

    _private_check($symbol)
        return true if the symbol should be considered private

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
    Determine if ancestor packages declare things left undocumented
    Widen the rules for identifying documentation
    Improve the code coverage of the test suite. "Devel::Cover" rocks so
    hard.
HISTORY
    Version 0.08 2001-11-14
        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

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

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

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

    Version 0.04
        Just 0.03 with a correctly generated README file

    Version 0.03
        Applied a patch from Dave Rolsky (barely 6 hours after release of
        0.02) to improve scanning of pod markers.

    Version 0.02
        Fixed up the import form. Removed dependency on List::Util. Added
        naked method. Exposed private configuration.

    Version 0.01
        As #london.pm invaded Brighton, people taked about documentation
        standards. mstevens scribbled something down, richardc coded it, the
        rest is ponies.

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

AUTHORS
    Richard Clamp <richardc@unixbeard.net>

    Michael Stevens <mstevens@etla.org>

    Copyright (c) 2001 Richard Clamp, Micheal Stevens. All rights reserved.
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

