Nadim Khemir wrote:
'method docs have examples': I believe the examples should be tested.
I have to disagree. Examples will often show you how to use a method
but not bother specifying values. Variables will often be used without
declaring them, and the example code for a method will assume that
you've bothered to load the module and instantiate it. You might also
see things like this:
=item current_location
Returns a two element list of the device's current latitude and
longitude. This is only valid for mobile devices. Calling it is a
fatal error for immobile devices.
($lat, $long) = $device->current_location();
How on earth do you propose to automagically test that *that* behaves
correctly? Just to make things even more awkward, that method's
documentation then goes on to say:
If you pass a latitude and longitude to the method, then the device
will attempt to move to the specified location, and the method will
return true or false depending on whether it could work out a route
to follow. Further calls to the method will either (depending on how
you invoke it) either tell you the current location or will cause it
to abandon its current journey and attempt to plot a new course.
And no, saying that the author will need to write some kind of exception
rule to tell it not to automagically test that example is not going to
work. Authors will say "screw that, it's too much like hard work, I'll
just not use that annoying doco-testing module".
And finally, consider whether you would even want to automatically test
the example given for the "delete_everything_in_my_home_directory"
function. The author can manually write tests for that by, for example,
mocking readdir() and unlink(), but you really *really* don't want to
automatically write a test for it.
--
David Cantrell
