1Test::Pod(3)          User Contributed Perl Documentation         Test::Pod(3)
2
3
4

NAME

6       Test::Pod - check for POD errors in files
7

VERSION

9       Version 1.52
10

SYNOPSIS

12       "Test::Pod" lets you check the validity of a POD file, and report its
13       results in standard "Test::Simple" fashion.
14
15           use Test::Pod tests => $num_tests;
16           pod_file_ok( $file, "Valid POD file" );
17
18       Module authors can include the following in a t/pod.t file and have
19       "Test::Pod" automatically find and check all POD files in a module
20       distribution:
21
22           use Test::More;
23           eval "use Test::Pod 1.00";
24           plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
25           all_pod_files_ok();
26
27       You can also specify a list of files to check, using the
28       all_pod_files() function supplied:
29
30           use strict;
31           use Test::More;
32           eval "use Test::Pod 1.00";
33           plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
34           my @poddirs = qw( blib script );
35           all_pod_files_ok( all_pod_files( @poddirs ) );
36
37       Or even (if you're running under Apache::Test):
38
39           use strict;
40           use Test::More;
41           eval "use Test::Pod 1.00";
42           plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
43
44           my @poddirs = qw( blib script );
45           use File::Spec::Functions qw( catdir updir );
46           all_pod_files_ok(
47               all_pod_files( map { catdir updir, $_ } @poddirs )
48           );
49

DESCRIPTION

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

FUNCTIONS

55   pod_file_ok( FILENAME[, TESTNAME ] )
56       pod_file_ok() will okay the test if the POD parses correctly.  Certain
57       conditions are not reported yet, such as a file with no pod in it at
58       all.
59
60       When it fails, pod_file_ok() will show any pod checking errors as
61       diagnostics.
62
63       The optional second argument TESTNAME is the name of the test.  If it
64       is omitted, pod_file_ok() chooses a default test name "POD test for
65       FILENAME".
66
67   all_pod_files_ok( [@entries] )
68       Checks all the files under @entries for valid POD. It runs
69       all_pod_files() on directories and assumes everything else to be a file
70       to be tested. It calls the plan() function for you (one test for each
71       file), so you can't have already called "plan".
72
73       If @entries is empty or not passed, the function finds all POD files in
74       files in the blib directory if it exists, or the lib directory if not.
75       A POD file matches the conditions specified below in "all_pod_files".
76
77       If you're testing a module, just make a t/pod.t:
78
79           use Test::More;
80           eval "use Test::Pod 1.00";
81           plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
82           all_pod_files_ok();
83
84       Returns true if all pod files are ok, or false if any fail.
85
86   all_pod_files( [@dirs] )
87       Returns a list of all the POD files in @dirs and in directories below.
88       If no directories are passed, it defaults to blib if blib exists, or
89       else lib if not. Skips any files in CVS, .svn, .git and similar
90       directories. See %Test::Pod::ignore_dirs for a list of them.
91
92       A POD file is:
93
94       •   Any file that ends in .pl, .PL, .pm, .pod, .psgi or .t.
95
96       •   Any file that has a first line with a shebang and "perl" on it.
97
98       •   Any file that ends in .bat and has a first line with "--*-Perl-*--"
99           on it.
100
101       The order of the files returned is machine-dependent.  If you want them
102       sorted, you'll have to sort them yourself.
103

SUPPORT

105       This module is managed in an open GitHub repository
106       <http://github.com/perl-pod/test-pod/>. Feel free to fork and
107       contribute, or to clone <git://github.com/perl-pod/test-pod.git> and
108       send patches!
109
110       Found a bug? Please post <http://github.com/perl-pod/test-pod/issues>
111       or email <mailto:bug-test-pod@rt.cpan.org> a report!
112

AUTHORS

114       David E. Wheeler <david@justatheory.com>
115           Current maintainer.
116
117       Andy Lester "<andy at petdance.com>"
118           Maintainer emeritus.
119
120       brian d foy
121           Original author.
122

ACKNOWLEDGEMENTS

124       Thanks brian d foy for the original code, and to these folks for
125       contributions:
126
127       •   Andy Lester
128
129       •   David E. Wheeler
130
131       •   Paul Miller
132
133       •   Peter Edwards
134
135       •   Luca Ferrari
136

138       Copyright 2006-2010, Andy Lester; 2010-2015 David E. Wheeler. Some
139       Rights Reserved.
140
141       This module is free software; you can redistribute it and/or modify it
142       under the same terms as Perl itself.
143
144
145
146perl v5.36.0                      2023-01-20                      Test::Pod(3)
Impressum