| When defining an API, every function or method should have some documentation explaining its purpose. That's a good goal ”one worth capturing in tests. Without requiring you to hardcode the name of every documented function, Test::Pod::Coverage can help you to ensure that all the subroutines you expect other people to use have proper POD documentation. How do I do that? Assume that you have a module distribution for a popular auto-racing sport. The distribution's base directory contains a t/ directory with tests and a lib/ directory with modules. Create a test file, t/pod-coverage.t , that contains the following:
Note: Module::Starter creates a podcoverage. t test file if you use it to create the framework for your distribution .
use Test::More; eval 'use Test::Pod::Coverage 1.04'; plan( skip_all => 'Test::Pod::Coverage 1.04 required for testing POD coverage' ) if $@; all_pod_coverage_ok( );
Run the test file with prove to see output similar to: $ prove -v t/pod-coverage.t t/pod-coverage....1..3 not ok 1 - Pod coverage on Sports::NASCAR::Car # Failed test (/usr/local/share/perl/5.8.4/Test/Pod/Coverage.pm at line 112) # Coverage for Sports::NASCAR::Car is 75.0%, with 1 naked subroutine: # restrictor_plate ok 2 - Pod coverage on Sports::NASCAR::Driver ok 3 - Pod coverage on Sports::NASCAR::Team # Looks like you failed 1 tests of 3. dubious Test returned status 1 (wstat 256, 0x100) DIED. FAILED test 1 Failed 1/3 tests, 66.67% okay Failed Test Stat Wstat Total Fail Failed List of Failed --------------------------------------------------------------------------- t/pod-coverage.t 1 256 3 1 33.33% 1 Failed 1/1 test scripts, 0.00% okay. 1/3 subtests failed, 66.67% okay.
What just happened ? The test file starts as normal, setting up paths to load the modules to test. The second and third lines of t/pod-coverage.t check to see whether the Test::Pod::Coverage module is available. If is isn't, the tests cannot continue and the test exits. Test::Pod::Coverage exports the all_pod_coverage_ok( ) function, which finds all available modules and tests their POD coverage. It looks for a lib/ or blib/ directory in the current directory and plans one test for each module that it finds. Unfortunately, the output of the prove command reveals that there's some work to do: the module Sports::NASCAR::Car is missing some documentation for a subroutine called restrictor_plate( ) . Further investigation of lib/Sports/NASCAR/Car.pm reveals that documentation is lacking indeed: =head2 make Returns the make of this car, e.g., "Dodge". =cut sub make { ... } sub restrictor_plate { ... }
In the previous listing, make( ) has documentation, but restrictor_plate( ) has none. Pod::Coverage considers a subroutine to have documentation if there exists an =head or =item that describes it somewhere in the module. The restrictor_plate( ) subroutine clearly lacks either of these. Add the following to satisfy that heuristic: =head2 make Returns the make of this car, e.g., "Dodge". =cut sub make { ... } =head2 restrictor_plate Returns whether this car has a restrictor plate installed. =cut sub restrictor_plate { ... }
Run the test again to see it pass: $ prove -v t/pod-coverage.t t/pod-coverage....1..3 ok 1 - Pod coverage on Sports::NASCAR::Car ok 2 - Pod coverage on Sports::NASCAR::Driver ok 3 - Pod coverage on Sports::NASCAR::Team ok All tests successful. Files=1, Tests=3, 1 wallclock secs ( 0.51 cusr + 0.03 csys = 0.54 CPU)
What about... | Q: | I have private functions that I don't want to document, but Test::Pod::Coverage complains that they don't have documentation. How can I fix that? | | A: | See the Test::Pod::Coverage documentation for the also_private and TRustme parameters. These come from Pod::Coverage , which also has good documentation well worth reading. By default, Test::Pod::Coverage makes some smart assumptions that functions beginning with underscores and functions with names in all caps are private. | | 