-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Nadim Khemir wrote:
>
>> 'method docs have examples': I believe the examples should be tested.
>
David Cantrell wrote:
> I have to disagree. [...] Authors will say "screw that, it's too
> much like hard work, I'll just not use that annoying doco-testing
> module".
Well I have been doing POD testing for a while now, and that sure
means more work, but also results in the ability for my cow-orkers to
rely on my =head1 SYNOPSIS docos to actually be useful. And I would
expect as much from a quality CPAN module given that the synopsis
section is pretty much part of the boilerplate these days (see
Module::Starter).
> Examples will often show you how to use a method but not bother
> specifying values.
That's an easy one: just munge the code-in-POD a bit with Perl before
eval'ing it. Here are some (approximative) excerpts from
Crypt::OpenSSL::CA:
=for My::Tests::Below "set_extension subjectKeyIdentifier" begin
$cert->set_extension( subjectKeyIdentifier => "00:DE:AD:BE:EF");
=for My::Tests::Below "set_extension subjectKeyIdentifier" end
And then in the test suite:
my $code = My::Tests->pod_code_snippet
("set_extension subjectKeyIdentifier");
eval <<"SUB_FROM_POD"; die $@ if $@;
sub set_extensions_like_in_the_POD {
my (\$cert) = [EMAIL PROTECTED];
my \$dnobj = Crypt::OpenSSL::CA::X509_NAME->new
(CN => "bogus issuer");
$code
}
SUB_FROM_POD
my $cert = Crypt::OpenSSL::CA::X509->new($eepubkey);
set_extensions_like_in_the_POD($cert);
like($cert->dump, qr/bogus issuer/); # And so on
> =item current_location
This is a standard testability issue that has nothing to do with the
code to test being in the POD or not. The solution here may involve
mocking the GPS receptor class and the wheels. (I know you know that,
I'm just dotting the i's so as not to conflate issues.)
> you really *really* don't want to automatically write a test for it.
>
Well we could test that the code-in-POD compiles cleanly by wrapping
it in a sub (and even then we'd have to be wary of BEGIN blocks, side
effects in stuff we "use" and source filters), but yeah, automatic
testing is pretty much out of the question: code-in-POD has to be put
under test in the same way as the rest of the code, ie, by hand.
- --
<< Tout n'y est pas parfait, mais on y honore certainement les
jardiniers >>
Dominique Quatravaux <[EMAIL PROTECTED]>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iQCVAwUBRmfs//TYH7KfeIIFAQLolgP9E8HAiMPTUY0NgwVzu9MvUw/nmrZoEX62
QdDtoMLvuqwFVewGRUnStGmBfxPjGBXmTDYZi2mG/yNkWPHklOIYADUh0FWxg8EQ
0p3EMXOaBvdUT057sZLmtqWdkaXPz8tfyVmOSbtEYH27S5EV4CaEvCiKQc+MVxwO
wu0MD1PFR5g=
=te+T
-----END PGP SIGNATURE-----
