| The Plain Old Documentation format, or POD, is the standard for Perl documentation. Every Perl module distribution should contain some form of POD, whether in standalone .pod files or embedded in the modules and programs themselves . As you edit documentation in a project, you run the risk of making errors. While typos and omissions can be annoying and distracting, formatting errors can render your documentation incorrectly or even make it unusable. Missing an =cut on inline POD may cause bizarre failures by turning working code into documentation. Fortunately, a test suite can check the syntax of all of the POD in your distribution. How do I do that? Consider a module distribution for a popular racing sport. The directory structure contains a t/ directory for the tests and a lib/ directory for the modules and POD documents. To test all of the POD in a distribution, create an extra test file, t/pod.t , as follows : 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( );
Run the test file with prove : $ prove -v t/pod.t t/pod....1..3 ok 1 - lib/Sports/NASCAR/Car.pm ok 2 - lib/Sports/NASCAR/Driver.pm ok 3 - lib/Sports/NASCAR/Team.pm ok All tests successful. Files=1, Tests=3, 0 wallclock secs ( 0.45 cusr + 0.03 csys = 0.48 CPU)
What just happened ? Because Test::Pod is a prerequisite only for testing, it's an optional prerequisite for the distribution. The second and third lines of t/pod.t check to see whether the user has Test::Pod installed. If not, the test file skips the POD-checking tests.
Note: People who build modules likely need to run the tests. People who install prebuilt packages may not .
One of the test functions exported by Test::Pod is all_pod_files_ok( ) . If given no arguments, it finds all Perl- related files in a blib/ or lib/ directory within the current directory. It declares a plan, planning one test per file found. The previous example finds three files, all of which have valid POD. If Test::Pod finds a file that doesn't contain any POD at all, the test for that file will be a success. What about... | Q: | How can I test a specific list of files? | | A: | Pass all_pod_files_ok( ) an array of filenames of all the files to check. For example, to test the three files that Test::Pod found previously, change t/pod.t to: 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( 'lib/Sports/NASCAR/Car.pm', 'lib/Sports/NASCAR/Driver.pm', 'lib/Sports/NASCAR/Team.pm' );
| | Q: | Should I ship POD-checking tests with my distribution? | | A: | There's no strong consensus in the Perl QA community one way or the other, except that it's valuable for developers to run these tests before releasing a new version of the project. If the POD won't change as part of the build process, asking users to run the tests may have little practical value besides demonstrating that you consider the validity of your documentation to be important. For projects released to the CPAN, the CPAN Testing Service (http://cpants.dev.zsi.at/) currently considers the presence of POD-checking tests as a mark of "kwalitee" (see Validating Kwalitee ," later in this chapter). Not everyone agrees with this metric. | |
