in reply to Documenting Thrown Exceptions

I suggest you learn more about pod by reading perlpod and perlpodspec. 
=head2 launch_nuclear_missles 

Throws

=over4

=item YAD

=item YADA

=back

=head2 launch_nuclear_missles 

=head3 Throws

=head4 YAD

the one yad

=head4 YADA

the one yada

=head2 launch_nuclear_missles 

=begin Throws

=item YAD - the one yad

=item YADA - the one yada

=end Throws

=cut

[download]
update: here it is, the ultimate stroke of genius, lol 
=for javadoc launch_nuclear_missles 
@throws LaunchException  Failed to launch
@throws ExplodeException Failed to explode

=cut

[download]

MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
** The third rule of perl club is a statement of fact: pod is sexy.

Replies are listed 'Best First'.
Re: Re: Documenting Thrown Exceptions
by halley (Prior) on Jul 11, 2003 at 18:50 UTC
    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 ]

[reply]
[d/l]

In Section Seekers of Perl Wisdom