module-build-general

[Module-build-general] idea for enhanced POD testing

[Mark S. <ma...@su...>]

Hello,

You've probably noticed the new feature on search.cpan.org that now
explains POD errors found in Perl modules as part of the documentation
display. I think is useful. Something that would complement this would
be the ability to easily test all the pod when running  "./Build test",
rather than noticing the errors after they have been made public.

This is already fairly easy by using the below test script.

However,  there still seems like a better solution should be available
than including the same test script in every module distribution.

Instead, this seems like a service that it could be reasonable for
Module::Build to offer.

Perhaps running "./Build testpod" could run this test.

Although this wouldn't be run as part of the standard install process I
think that's OK. What seems important is that the /developer/ be able to
run the test, while it's less important to make this easy for the
/user/ to test pod. 


	Mark

--
http://mark.stosberg.com/ 

#####

/usr/src/.cpanplus/5.8.0/build/Data-FormValidator-3.11/t/99_pod.t
use Test::More;

# Check our Pod
# The test was provided by Andy Lester,
# who stole it from Brian D. Foy
# Thanks to both !

use File::Spec;
use File::Find;
use strict;

eval {
  require Test::Pod;
  Test::Pod->import;
};

my @files;

if ($@) {
  plan skip_all => "Test::Pod required for testing POD";
}
elsif ($Test::Pod::VERSION < 0.95) {
  plan skip_all => "Test::Pod 0.95 required for testing POD";
}
else {
  my $blib = File::Spec->catfile(qw(blib lib));
  find(\&wanted, $blib, 'bin');
  plan tests => scalar @files;
  foreach my $file (@files) {
    pod_file_ok($file);
  }
}

sub wanted {
  push @files, $File::Find::name if /\.p(l|m|od)$/;
}

__END__

Re: [Module-build-general] idea for enhanced POD testing

[Steve P. <sp...@qu...>]

Hi Mark,

That's not a bad idea - I've seen scripts that do similar things with 
File::Find::Rule, and they can be quite useful.  Still, I'd say the 
developer can check the output of './Build docs' for errors, though I 
agree it's not as nice an interface.  Your argument might be more 
persuasive with a patch?

In terms of implementation, you'd want to run it on the same pod files 
as those found in manify_bin_pods() and manify_lib_pods().  Which 
likely means you'd need to factor out methods like _lib_pods() and 
_bin_pods() to avoid re-inventing the wheel, something like:

   sub _bin_pods {
     my $self  = shift;
     return $self->_find_pods($self->{properties}{bindoc_dirs});
   }

And write an ACTION to run those through Test::Pod.

-Steve


On Sunday, September 28, 2003, at 05:23  pm, Mark Stosberg wrote:

> Hello,
>
> You've probably noticed the new feature on search.cpan.org that now
> explains POD errors found in Perl modules as part of the documentation
> display. I think is useful. Something that would complement this would
> be the ability to easily test all the pod when running  "./Build test",
> rather than noticing the errors after they have been made public.
>
> This is already fairly easy by using the below test script.
>
> However,  there still seems like a better solution should be available
> than including the same test script in every module distribution.
>
> Instead, this seems like a service that it could be reasonable for
> Module::Build to offer.
>
> Perhaps running "./Build testpod" could run this test.
>
> Although this wouldn't be run as part of the standard install process I
> think that's OK. What seems important is that the /developer/ be able 
> to
> run the test, while it's less important to make this easy for the
> /user/ to test pod.
>
>
> 	Mark
>
> --
> http://mark.stosberg.com/
>
> #####
>
> /usr/src/.cpanplus/5.8.0/build/Data-FormValidator-3.11/t/99_pod.t
> use Test::More;
>
> # Check our Pod
> # The test was provided by Andy Lester,
> # who stole it from Brian D. Foy
> # Thanks to both !
>
> use File::Spec;
> use File::Find;
> use strict;
>
> eval {
>   require Test::Pod;
>   Test::Pod->import;
> };
>
> my @files;
>
> if ($@) {
>   plan skip_all => "Test::Pod required for testing POD";
> }
> elsif ($Test::Pod::VERSION < 0.95) {
>   plan skip_all => "Test::Pod 0.95 required for testing POD";
> }
> else {
>   my $blib = File::Spec->catfile(qw(blib lib));
>   find(\&wanted, $blib, 'bin');
>   plan tests => scalar @files;
>   foreach my $file (@files) {
>     pod_file_ok($file);
>   }
> }
>
> sub wanted {
>   push @files, $File::Find::name if /\.p(l|m|od)$/;
> }
>
> __END__
>
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by:ThinkGeek
> Welcome to geek heaven.
> http://thinkgeek.com/sf
> _______________________________________________
> Module-build-general mailing list
> Mod...@li...
> https://lists.sourceforge.net/lists/listinfo/module-build-general