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.

Makeshifts last the longest.

Great idea! Here's a quick and dirty implementation:

package Module::Build::SillyPodTests;

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;
[download]

Use this in place of Module::Build in your Build.PL file and the only suck is that you still have to distribute the why-make-users-run-them POD testing files.

Edited somewhat.

Well, what's the point in having your module pods (not just coverage) tested on every machine where it is installed?

I agree 100%. My problem was caused by a module that I listed as a dependency. It's very annoying. Someone can't install my module because a module that I have as a prereq fails to pass a coverage test -- falsely -- because of an outdated Pod::Coverage on the tester's machine.

Some tests are not there just to ensure that things are working, but rather to ensure the user that the author did take his time to do things properly.

I, for one, enjoy seeing that the author took the time to make sure he was documenting every single function in his code.

I could accidentally distribute in a .svn/ directory to "prove" that I use source control too, but it wouldn't do you much good. (Actually I couldn't; I use svk.)

Some tests are not there just to ensure that things are working, but rather to ensure the user that the author did take his time to do things properly.

Running a test doesn't say anything more than that the author managed to write code that produced output in the form:

    print 1..3
    ok 1
    ok 2
    ok 3
[download]

If you want to know the author did things properly, you'd run your tests, not the authors.

I, for one, enjoy seeing that the author took the time to make sure he was documenting every single function in his code.

I'd rather see a manual page that documents the API. Not every function belongs to the API - the more complex a functionality is that a module delivers, the lower the ratio of API functions vs total number of functions will be. Documenting functions belongs in source code comments. POD is user documentation.
Perl --((8:>*

Test::Pod::Coverage does ignore subroutines with names that start with an underscore, so if you use that particular convention you'll only have to document the subs that are part of the interface (i.e. not private).

I agree wholeheartedly though, documentation of private functions does not belong in the pod, that's what comments are there for.


Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. -- Brian W. Kernighan

=begin apidoc

=item _FooBar

=end apidoc

=cut
[download]

Bit verbose but thats pod for you. Too bad there isn't a =finish directive that combined 'end X' with cut. Ie,

=finish apidoc
[download]

would be a convenient shortcut for

=end apidoc

=cut
[download]

---
$world=~s/war/peace/g