develooper Front page | perl.module-authors | Postings from November 2005

Another CPANTS/pod_coverage.t rant - FULL VERSION

Thread Next
From:
David Golden
Date:
November 13, 2005 06:36
Subject:
Another CPANTS/pod_coverage.t rant - FULL VERSION
Message ID:
43774F4F.4060501@hyperbolic.net
[Apologies -- I hit the send button prematurely by mistake when trying to 
click on something else.  Continuing...]

I just got bit by an annoying problem, at least part of which highlights a 
reason why I think that encouraging people to blindly add boilerplate 
pod_coverage.t files is not a good practice.  Or, more constructively, I'd 
like to suggest that the way boilerplate pod_coverage.t file are recommended 
be changed.

Description of the problem:

* A prereq module of mine uses a pod_coverage.t file, similar to what 
Module::Starter::PBP recommends:

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

* The module in question needs a Pod::Coverage of at least 0.16 given the 
style of documentation it uses

* Test::Pod::Coverage has Pod::Coverage prereq of 0

Clearly the module author had a sufficiently high Pod::Coverage to pass (as 
did I).  However, anyone trying to install with an older version of 
Pod::Coverage will fail the coverage test.  The skip_all doesn't help 
because it only checks that Test::Pod::Coverage exists, not that 
Pod::Coverage is actually sufficient to pass the tests, and 
Test::Pod::Coverage doesn't care what underlying Pod::Coverage is used.

Side nit, the docs for Test::Pod::Coverage don't even recommend checking for 
the latest Test::Pod::Coverage to address its bugs:

> use Test::More;
> eval "use Test::Pod::Coverage 1.00";
> plan skip_all => "Test::Pod::Coverage 1.00 required for testing POD coverage" if $@;
> all_pod_coverage_ok();

Leaving aside the old flame war point about whether end users ought to be 
running coverage checks with all the associated dependency issues that have 
nothing to do with whether the module works correctly (with my bias here 
clearly evident), if we have to have boilerplate pod coverage tests, I'd 
much rather see boilerplate like this, that highlights the Pod::Coverage 
dependency, too:

   use Test::More;
   # MODULE AUTHORS: UPDATE VERSIONS BELOW TO MATCH YOUR CONFIGURATION
   eval "use Pod::Coverage 0.17 ()";
   plan skip_all => "Pod::Coverage 0.17 required for testing POD coverage" 
if $@;
   eval "use Test::Pod::Coverage 1.06";
   plan skip_all => "Test::Pod::Coverage 1.06 required for testing POD 
coverage" if $@;
   all_pod_coverage_ok();

Thoughts?  If we can get a consensus on this or a similar approach, then 
perhaps we can get it consistently used across Module::Starter and friends, 
ExtUtils::ModuleMaker and friends, and CPANTS documentation.

Sincerely,
David Golden

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About