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/, and /^AUTOLOAD/.

        "also_private" is similar to "private" but these are appended to the
        default set

    $object->coverage
        Gives the coverage as a value in the range 0 to 1

    $object->naked
        Returns a list of uncovered routines, will implicitly call coverage
        if it's not already been called.

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.

    Also the code currently only deals with packages in their own .pm files,
    this will be adressed with the next release.

TODO
    Examine globals and explicitly exported symbols
    Determine if ancestor packages declare things left undocumented
    Widen the rules for identifying documentation
    Look for a correponding .pod file to go with your .pm file
        This is typical of code like Data::Dumper and
        Quantum::Superpositions, which have extensive documentation, but
        Pod::Coverage declares them to have none.

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

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.

