Especially for object-oriented modules, but not limited to such, I would far prefer a summary DIAGNOSTICS section over a per-sub discussion of errors. That is, don't bury the reader with paper, but instead illuminate the overall concept.

=head1 NAME
=head1 SYNOPSIS
=head1 ABSTRACT and/or a more detailed DESCRIPTION
=head1 METHODS
=head2 method()
=head1 DIAGNOSTICS
=head1 FILES and/or SEE ALSO
=head1 AUTHOR and/or COPYRIGHT and/or LICENSE
[download]

In Java APIs which I've seen (and written), the documentation often goes overboard in automatically generating reams and reams of content with little value. The traditional shortcoming in reference documentation is that it doesn't focus on usage patterns, but focuses on the enumeration of every detail in isolation. Lots of what, almost no how or why.

In Perl and other documentation, I prefer to paint the bold strokes that let an uninitiated user understand the how and why. The what is important, but can't be the only thing listed.

--
[ e d @ h a l l e y . c c ]