Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Ovid (2709)

Ovid
  (email not shown publicly)
http://publius-ovidius.livejournal.com/
AOL IM: ovidperl (Add Buddy, Send Message)

Stuff with the Perl Foundation. A couple of patches in the Perl core. A few CPAN modules. That about sums it up.

Journal of Ovid (2709)

Monday September 25, 2006
08:08 AM

Better POD coverage for work

[ #31116 ]

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();
};

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.