Test::Pod (3)

Leading comments

Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Test::Pod.3pm".)

NAME

Test::Pod - check for POD errors in files

VERSION

Version 1.51

SYNOPSIS

"Test::Pod" lets you check the validity of a 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

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 Apache::Test):

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

is the name of the test. If it is omitted, "pod_file_ok()" chooses a default test name `` test for

all_pod_files_ok( [@entries] )

Checks all the files under @entries for valid It runs all_pod_files() on directories and assumes everything else to be a file to be tested. It calls the "plan()" function for you (one test for each file), so you can't have already called "plan".

If @entries is empty or not passed, the function finds all

files in files in the blib directory if it exists, or the lib directory if not. A file is one that ends with a Perl extension (.pod, .pl, .pm, .PL, .t), where the first line looks like a Perl shebang, or a batch file (.bat) starting with a line containing "--*-Perl-*--".

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 @dirs 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 , .svn, .git and similar directories. See %Test::Pod::ignore_dirs for a list of them.

A Perl file is:

*

Any file that ends in .PL, .pl, .PL, .pm, .pod, or .t.

*

Any file that has a first line with a shebang and ``perl'' on it.

*

Any file that ends in .bat and has a first line with ``--*-Perl-*--'' on it.

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

SUPPORT

This module is managed in an open GitHub repository <github.com/perl-pod/test-pod>. Feel free to fork and contribute, or to clone <git://github.com/perl-pod/test-pod.git> and send patches!

Found a bug? Please post <github.com/perl-pod/test-pod/issues> or email <mailto:bug-test-pod@rt.cpan.org> a report!

AUTHORS

David E. Wheeler <david@justatheory.com>

Current maintainer.

Andy Lester <andy at petdance.com>

Maintainer emeritus.

brian d foy

Orinal author.

ACKNOWLEDGEMENTS

Thanks brian d foy for the original code, and to these folks for contributions:

*

Andy Lester

*

David E. Wheeler

*

Paul Miller

*

Peter Edwards

*

Luca Ferrari

COPYRIGHT AND LICENSE

Copyright 2006-2010, Andy Lester; 2010-2015 David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.