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 ]

In reply to Re: Re: Documenting Thrown Exceptions by halley
in thread Documenting Thrown Exceptions by hardburn

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.