NAME

Test::Pod - check for POD errors in files

VERSION

Version 1.26

SYNOPSIS

Test::Pod lets you check the validity of a POD file, and report its results in standard Test::Simple fashion.

    use Test::Pod tests => $num_tests;
    pod_file_ok( $file, "Valid POD file" );

Module authors can include the following in a t/pod.t file and have Test::Pod automatically find and check all POD files in a module distribution:

    use Test::More;
    eval "use Test::Pod 1.00";
    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
    all_pod_files_ok();

You can also specify a list of files to check, using the all_pod_files() function supplied:

    use strict;
    use Test::More;
    eval "use Test::Pod 1.00";
    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
    my @poddirs = qw( blib script );
    all_pod_files_ok( all_pod_files( @poddirs ) );

Or even (if you're running under the Apache::Test manpage):

    use strict;
    use Test::More;
    eval "use Test::Pod 1.00";
    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;

    my @poddirs = qw( blib script );
    use File::Spec::Functions qw( catdir updir );
    all_pod_files_ok(
        all_pod_files( map { catdir updir, $_ } @poddirs )
    );

DESCRIPTION

Check POD files for errors or warnings in a test file, using Pod::Simple to do the heavy lifting.

FUNCTIONS

pod_file_ok( FILENAME[, TESTNAME ] )

pod_file_ok() will okay the test if the POD parses correctly. Certain conditions are not reported yet, such as a file with no pod in it at all.

When it fails, pod_file_ok() will show any pod checking errors as diagnostics.

The optional second argument TESTNAME is the name of the test. If it is omitted, pod_file_ok() chooses a default test name ``POD test for FILENAME''.

all_pod_files_ok( [@files/@directories] )

perldoc2tree.cgi: /usr/lib/perl5/site_perl/5.8.8/Test/Pod.pm: cannot resolve L in paragraph 41.

Checks all the files in @files for valid POD. It runs all_pod_files() on each file/directory, and calls the plan() function for you (one test for each function), so you can't have already called plan.

If @files is empty or not passed, the function finds all POD files in the blib directory if it exists, or the lib directory if not. A POD file is one that ends with .pod, .pl and .pm, or any file where the first line looks like a shebang line.

If you're testing a module, just make a t/pod.t:

    use Test::More;
    eval "use Test::Pod 1.00";
    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
    all_pod_files_ok();

Returns true if all pod files are ok, or false if any fail.

all_pod_files( [@dirs] )

Returns a list of all the Perl files in $dir and in directories below. If no directories are passed, it defaults to blib if blib exists, or else lib if not. Skips any files in CVS or .svn directories.

A Perl file is:

Any file that ends in .PL, .pl, .pm, .pod or .t.
Any file that has a first line with a shebang and ``perl'' on it.

The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself.

TODO

STUFF TO DO

Note the changes that are being made.

Note that you no longer can test for ``no pod''.

AUTHOR

Currently maintained by Andy Lester, <andy at petdance.com>.

Originally by brian d foy.

ACKNOWLEDGEMENTS

Thanks to David Wheeler and Peter Edwards for contributions and to brian d foy for the original code.

COPYRIGHT

You may use, modify, and distribute this package under the same terms as Perl itself.