Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
Andy Lester wrote: Patches to Module::Starter are always welcome. My ears are always open. Your ideas make sense, especially about noting the Pod::Coverage version. I don't suppose you'd want a patch to drop pod/pod-coverage testing entirely? ;-) Since I'm in the opposed camp, I don't really want to put spare tuits to something I don't support in the first place. How about one that makes pod/pod-coverage skip-all by default unless the author explicitly changes the .t files to turn them on? (Opt-in versus opt-out). That way it's a convenient option, not a recommendation to authors. If that patch would go through, I'd add the Pod::Coverage version test for free. David
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
* David Golden [EMAIL PROTECTED] [2005-11-14 13:45]:
How about one that makes pod/pod-coverage skip-all by default
unless the author explicitly changes the .t files to turn them
on?
In http://www.perlmonks.org/index.pl?node_id=508155 I wrote:
A better approach would be to make their execution depend on
the action, so someone saying `./Build disttest` would get
them, whereas someone saying `./Build test` would not.
To which chromatic reacted in
http://www.perlmonks.org/index.pl?node_id=508160:
Great idea! Here's a quick and dirty implementation:
package Module::Build::StupidPodTests;
use SUPER;
use base 'Module::Build';
use Module::Build;
sub ACTION_disttest
{
my $self = shift;
local $ENV{PERL_TESTPOD} = 1;
super();
}
sub find_test_files
{
my $self = shift;
my $tests = super();
return $tests if $ENV{PERL_TESTPOD};
return [ grep { $_ !~ /\bpod.*\.t\z/ } @$tests ];
}
1;
Use this in place of Module::Build in your Build.PL file and
the only suck is that you still have to distribute the
still-useless-to-everyone-else-but-CPANTS-for-some-reason POD
testing files.
But at this point, I think even this is not quite the right
approach. Rather, the tests should be built directly into
Module::Build itself à la the `testcover` target. Test::Pod needs
no parametrisation, so it would be trivial to integrate, and it
also is the really valuable test. (At least I can’t think of
*any* case where letting malformed POD through is desirable.)
Test::Pod::Coverage will often need handholding (“yes, I’ve
documented the constructor, even though you can’t tell, silly
thing”), and would thus require some configuration mechanism. Or
it might just be left out, I wouldn’t care. I can only think of
one scenario where it is useful: as a rough guide for
retrospectively adding POD to a complex, un(der)documented suite
of modules.
As far as CPANTS is concerned, awarding points for the respective
issues by checking the metrics themselves is a good idea, but
looking for tests for these metrics seems rather pointless.
Again, checking whether the POD is error-free is arguably
valuable; checking POD coverage is questionable.
Regards,
--
#Aristotle
*AUTOLOAD=*_=sub{s/(.*)::(.*)/print$2,(,$\/, )[defined wantarray]/e;$1};
Just-another-Perl-hacker;
RE: Another CPANTS/pod_coverage.t rant - FULL VERSION
Title: RE: Another CPANTS/pod_coverage.t rant - FULL VERSION As far as CPANTS is concerned, awarding points for the respective issues by checking the metrics themselves is a good idea, but looking for tests for these metrics seems rather pointless. Again, checking whether the POD is error-free is arguably valuable; checking POD coverage is questionable. We needa Kwalitee Kwalitee Metric. Anything that attempts to use Pod::Coverage to determine Kwalitee is inherently of low Kwalitee and should lose points. Yves
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
A. Pagaltzis wrote: But at this point, I think even this is not quite the right approach. Rather, the tests should be built directly into Module::Build itself à la the `testcover` target. Test::Pod needs no parametrisation, so it would be trivial to integrate, and it also is the really valuable test. (At least I can’t think of *any* case where letting malformed POD through is desirable.) Pod syntax checking is there already as testpod. It would be fairly trivial to add testpodcover, but I suspect that never happened because testcover does it already through Devel::Cover. David
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
On Mon, Nov 14, 2005 at 08:56:32AM -0500, David Golden wrote: A. Pagaltzis wrote: But at this point, I think even this is not quite the right approach. Rather, the tests should be built directly into Module::Build itself à la the `testcover` target. Test::Pod needs no parametrisation, so it would be trivial to integrate, and it also is the really valuable test. (At least I can?t think of *any* case where letting malformed POD through is desirable.) I think this is the way to go. Pod syntax checking is there already as testpod. It would be fairly trivial to add testpodcover, but I suspect that never happened because testcover does it already through Devel::Cover. I would rather these were rolled into 'disttest', so I have less API to remember. The pod tests could possibly be reported in a separate result, so there would be a distinction between the functional tests and the kwalitee tests. I do realize there is merit the alternate viewpoint that from the user's perspective the functionality and overall quality contribute a single overall impression. Mark
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
* David Golden [EMAIL PROTECTED] [2005-11-14T08:56:32] Pod syntax checking is there already as testpod. It would be fairly trivial to add testpodcover, but I suspect that never happened because testcover does it already through Devel::Cover. Test::Pod::Coverage needs to evaluate the Perl code it is coverage-testing. It has been said that no CPANTS test will do that. -- rjbs pgp2xfUu1Cydq.pgp Description: PGP signature
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
Ricardo SIGNES wrote: * David Golden [EMAIL PROTECTED] [2005-11-14T08:56:32] Pod syntax checking is there already as testpod. It would be fairly trivial to add testpodcover, but I suspect that never happened because testcover does it already through Devel::Cover. Test::Pod::Coverage needs to evaluate the Perl code it is coverage-testing. It has been said that no CPANTS test will do that. Sorry for the confusion. I was responding to a query about Module::Build, which already does have a testpod action. E.g.: $ perl Build.PL $ Build $ Build test $ Build testpod Likewise, there's a testcover action that runs Devel::Cover on the test suite: $ Build testcover Devel::Cover will include pod coverage testing if Pod::Coverage is installed. David
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
On Mon, Nov 14, 2005 at 07:40:59AM -0500, David Golden ([EMAIL PROTECTED]) wrote: How about one that makes pod/pod-coverage skip-all by default unless the author explicitly changes the .t files to turn them on? No. Module::Starter is a case where I'm using the package as evangelism. Users can rm t/*.t; perl -ni -e'print unless m[t/pod]' MANIFEST if they don't like the tests. xoxo, Andy -- Andy Lester = [EMAIL PROTECTED] = www.petdance.com = AIM:petdance
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
* David Golden [EMAIL PROTECTED] [2005-11-14 15:00]: Pod syntax checking is there already as testpod. Ah. I even have a fairly recent version of Module::Build, but it seems I need to upgrade again. It would be fairly trivial to add testpodcover, but I suspect that never happened because testcover does it already through Devel::Cover. Cool! Yet more I didn’t know. You know, I like this Module::Build thing more and more… Regards, -- Aristotle Pagaltzis // http://plasmasturm.org/
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
Would it be useful for Module::Build to warn you if perl Build dist is run without a successful run of these tests? $ perl Built dist KWALITEE WARNING: It's recommended you run perl Build disttest beforehand. KWALITEE WARNING: It's recommended you run perl Build testpod beforehand. ... $ perl Build testpod perl Build disttest $ perl Build dist ... Module::Build could write some flag to indicate that a test were done and how successful it was. The flag probably should include a checksum of all files in the distribution to allow verification that the test was run on the current copy of the files. If your t/*.t files themselves handle these kwalitee tests (e.g. as a substitute for testpod), then these flags should get updated when running the t/*.t tests as well. If the flags are included in the distribution itself, they could be read by CPANTS to address problems like the below: Ricardo SIGNES wrote: Test::Pod::Coverage needs to evaluate the Perl code it is coverage-testing. It has been said that no CPANTS test will do that. --davidm
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
--- Andy Lester [EMAIL PROTECTED] wrote: No. Module::Starter is a case where I'm using the package as evangelism. If it's for evangalism, could we have Build.PL do the right thing and have Module::Starter::Simple add the following line? create_makefile_pl = 'traditional', The reasons are detailed in http://perlmonks.org/index.pl?node_id=458282 Cheers, Ovid -- If this message is a response to a question on a mailing list, please send follow up questions to the list. Web Programming with Perl -- http://users.easystreet.com/ovid/cgi_course/
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
On Nov 14, 2005, at 9:20 PM, Ovid wrote: --- Andy Lester [EMAIL PROTECTED] wrote: No. Module::Starter is a case where I'm using the package as evangelism. If it's for evangalism, could we have Build.PL do the right thing and have Module::Starter::Simple add the following line? create_makefile_pl = 'traditional', The reasons are detailed in http://perlmonks.org/index.pl?node_id=458282 Yes, send ticket to the RT queue. If it's already in there, we'll get to it. xoxo, Andy -- Andy Lester = [EMAIL PROTECTED] = www.petdance.com = AIM:petdance
Another CPANTS/pod_coverage.t rant - FULL VERSION
[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
Re: Another CPANTS/pod_coverage.t rant - FULL VERSION
There's a Dennis Miller bit I love. He's talking about how he's looking at an issue of Cosmopolitan and is horrified to see an article called Trick Your Man Into Making Tex-Mex. He's incredulous. Trick me? Fuckin' ASK ME! 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. Patches to Module::Starter are always welcome. My ears are always open. Your ideas make sense, especially about noting the Pod::Coverage version. xoxo, Andy -- Andy Lester = [EMAIL PROTECTED] = www.petdance.com = AIM:petdance
