Check for pod errors in files
Version 1.48
\*(C`Test::Pod\*(C' lets you check the validity of a \s-1POD\s0 file, and report its results in standard \*(C`Test::Simple\*(C' 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 \*(C`Test::Pod\*(C' automatically find and check all \s-1POD\s0 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 \*(C`all_pod_files()\*(C' 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 ) );
Check \s-1POD\s0 files for errors or warnings in a test file, using \*(C`Pod::Simple\*(C' to do the heavy lifting.
\*(C`pod_file_ok()\*(C' will okay the test if the \s-1POD\s0 parses correctly. Certain conditions are not reported yet, such as a file with no pod in it at all.
When it fails, \*(C`pod_file_ok()\*(C' will show any pod checking errors as diagnostics.
The optional second argument \s-1TESTNAME\s0 is the name of the test. If it is omitted, \*(C`pod_file_ok()\*(C' chooses a default test name \*(L"\s-1POD\s0 test for \s-1FILENAME\s0\*(R".
Checks all the files under @entries for valid \s-1POD\s0. It runs all_pod_files() on directories and assumes everything else to be a file to be tested. It calls the \*(C`plan()\*(C' function for you (one test for each file), so you can't have already called \*(C`plan\*(C'.
If @entries is empty or not passed, the function finds all \s-1POD\s0 files in files in the blib directory if it exists, or the lib directory if not. A \s-1POD\s0 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.
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 \s-1CVS\s0, .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 \*(L"perl\*(R" on it.
Any file that ends in .bat and has a first line with \*(L"--*-Perl-*--\*(R" on it.
The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself.
\s-1STUFF\s0 \s-1TO\s0 \s-1DO\s0
Note the changes that are being made.
Note that you no longer can test for \*(L"no pod\*(R".
Currently maintained by David E. Wheeler, \*(C`<[email protected]>\*(C'.
Originally by brian d foy.
Maintainer emeritus: Andy Lester, \*(C`<andy at petdance.com>\*(C'.
Thanks to Andy Lester, David Wheeler, Paul Miller and Peter Edwards for contributions and to \*(C`brian d foy\*(C' for the original code.
Copyright 2006-2010, Andy Lester. Some Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.