Better POD coverage for work

Ovid on 2006-09-25T13:08:54

When writing POD coverage tests for your company, modules can be loosely grouped into four categories:

1. Modules your company didn't write
2. Modules which can't be loaded (e.g., various Apache modules)
3. Modules with known incomplete POD
4. Modules with complete POD

For a straight POD coverage test, #2 and #3 are guaranteed to fail. #1 might fail, but you have little control over that. #4 is the only category in which the modules definitely pass. However, Test::Pod::Coverage might seem a bit confusing at first. The following test program handles those four cases.

Note that @modules_we_did_not_write, @modules_with_incomplete_pod and @modules_which_cannot_compile_directly will need to be replaced with your appropriate list of modules.

#!perl -T

use Test::More;

eval "use Test::Pod::Coverage 1.04";

my @modules;
if ( $@ ) {
    plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage";
}
else {
    @modules = get_module_list(@modules_we_did_not_write); # XXX
    plan tests => scalar @modules;
}

my $trustparents = { coverage_class => 'Pod::Coverage::CountParents' };

my %incomplete_pod_for = map { $_ => 1 } @modules_with_incomplete_pod; # XXX

# Not all modules load directly.  If they are good but we can't compile them
# directly, we go ahead and skip 'em.
my %compilation_errors_for = map { $_ => 1 } 
  @modules_which_cannot_compile_directly; # XXX

foreach my $module (@modules) {
    if ( $incomplete_pod_for{$module} ) {
        TODO: {
            local $TODO = "Incomplate POD for $module";
            pod_coverage_ok( $module, $trustparents );
        };
    }
    elsif ( $compilation_errors_for{$module} ) {
        SKIP: {
            skip "Cannot directly compile $module", 1;
        };
    }
    else {
        pod_coverage_ok( $module, $trustparents );
    }
}

sub get_module_list {
    my %ignore_pod_for = map { $_ => 1 } @_;
    return grep { !exists $ignore_pod_for{$_} }
        Test::Pod::Coverage::all_modules();
};