13.8. Documenting Errors
It's important to document every exception (or warning) your code may ever generate (see Chapter 7), but it's vital to do so in a way that will be comprehensible to the likely recipient of these messages.
For example, suppose someone uses your new Random::Utils module:
use Random::Utils qw( pick_from );# and later...$random_item = pick_from(@items);
And suppose that call to pick_from( ) causes their program to terminate unexpectedly with the message:
Can't pick a random element from an empty list at monte_carlo.pl line 42
If they're not familiar with your module, they may be unsure what the problem is, or what caused it, or what to do about it. In which case, you'd hope that they'll try and work out what to do by reading the fine Random::Utils manual[*].
That kind of self-help will be far more likely to happen if your documentation actually does help readers solve their problems. To achieve that goal, you first need to explain the problem more fully, in one or more complete sentences; sentences that are longerand written in less dense languagethan the error message itself. You should then describe the most common causes of the problem, and finally suggest how the offending code might be fixed. For example:
=head1 DIAGNOSTICS =over =item Can't pick an element from an empty list The C<pick_from( )> subroutine was called without any arguments, which meant it had no values to choose amongst. Perhaps you forgot to supply an argument to C<pick_from( )>. Alternatively, maybe you passed an array to the subroutine, but that array was empty at the time. If you need to pass C<pick_from( )> an array that might sometimes have no elements, try using the C<pick_with_default_from( )> subroutine instead (see L<Picking randomly with a fall-back value>).
The standard perldiag documentation is a superb example of this user-friendly approach to documenting exceptions and warnings. For example, it explains the mysteriously Zen-like Attempt to join self error message like so:
=item Attempt to join self (F) You tried to join a thread from within itself, which is an impossible task. You may be joining the wrong thread, or you may need to move the C<join( )> to some other thread.