Notice that $data, $length, and $verbose are declared with "my", but
$result is not.
(Of course, you could argue that $result was declared earlier in
the program, but then you could make that argument for $data, $length,
and $verbose as well.)
I would say that this kind of example is just that - an example. Or a
specification. It shows how to use the module, but whether some variable
used in the example has a "my" in front of it does not really matter. You
would certainly need to edit the code anyway, since your code will MOST
probably not need a "length", "file", "verbose" parameter. ;-)
I will usually put the "use strict;" and "use warnings;" lines
right into the SYNOPSIS section of the perldocs I write,
I only include the barest necessary code as a "wrapper" around whatever I
want to show. I assume that the reader of some module documentation knows
about strict, warnings, my etc. OTOH, I have no public modules, either,
and know the people who use mine.
My minimum form of POD is usually like this:
=head2 someFunc
($xyz,$abc) = MyModule::someFunc($def,$ghi);
Blablabla ...
=cut
This outputs the "signature" of the function prominently at the top, i.e.,
it tells the user what arguments I expect and what I return (of course, if
the sub is a difficult one, more examples may be added). But whether or
not "my" is in there does not really matter at all. The user is free to
cut&paste that "signature" to avoid some little amount of typing, but he
will usually already have other variable names in place, so the usefulness
of "cut&paste-ready" code seems limited, to me.
be honest, I'm not sure if that's a good habit or not (including them
in the perldocs, that is), but I figure if it gets a user to start
using 'strict' and 'warnings' (where they otherwise wouldn't), then
the positive of doing that outweighs the negative.
Yup, I guess it's philosophical. But I would very seldomly cut&paste some
code from the documentation with the intent of using it without any
further editing - it would in 99% of the cases simply not match my needs
(one notable exception is "perldoc -f localtime" - I frequently cut&paste
that beautiful line which includes the return values ;-) ).