put pod coverage exceptions in your pod

After having this task languish in my todo for years, at least, I have finally reduced my goal to the important 90% and applied some JFDI.

Pod::Coverage::TrustPod acts like Pod::Coverage::CountParents, but accepts non-whitespace lines inside “Pod::Coverage” POD targets as “trustme” instructions.

In otherwords, given this module:

package Foo;

=begin Pod::Coverage

  bar

=end Pod::Coverage

=head2 baz

This routine does stuff.

=cut

sub foo { ... }
sub bar { ... }
sub baz { ... }
sub _xyzzy { ... }

Pod::Coverage::TrustPod will return 2/3 coverage. _xyzzy is private, so uncounted. There are docs for baz, bar is trusted (because it’s in the Pod::Coverage =begin block) and there are no docs for foo.

The basic use case is that now my xt/pod-coverage can now read:

all_pod_coverage_ok({ coverage_class => 'Pod::Coverage::TrustPod' });

and the information on what code is written but undocumented can be put where it belongs – near the code that is written but undocumented. This will help eliminate both (A) marking a symbol trustme/also_private in all of a dist’s packages so that I can use all_pod_coverage_ok and (B) having to write a bunch of pod_coverage_ok lines to avoid problem A.

Written on March 27, 2008
perl   programming   testing