hardburn has asked for the wisdom of the Perl Monks concerning the following question:

A recent thread got me to start using Error.pm for error handling. I spent about three years coding Java before I started using Perl a lot, so I am familer with the idea behind this kind of exception handling.

Java has Javadocs, which is analgous to POD, except not as flexible and it carries some very Java-specific idioms. One of those specific idioms is documenting exceptions a method can throw (excuse me if this isn't quite right, as I've been away from Java for a while):

/**
 * Lauch Nuclear Missles.
 * 
 * @throws LaunchException  Failed to launch
 * @throws ExplodeException Failed to explode
 */
public void launchNuclearMissles(int megatons) 
    throws LaunchException, ExplodeException
{
    // Code which could throw a LaunchException and 
    // an ExplodeException
}

[download]

POD doesn't have an equivilent form. What I'm currently thinking of is along these lines:

=head2 launch_nuclear_missles 

  launch_nuclear_missles( $megatons );

  THROWS: 
  LaunchException  -- Failed to launch
  ExplodeException -- Failed to explode

Launches nuclear missles.

=cut

[download]

There is no whitespace on the line between the subroutine definition and the THROWS: line, so there will be a logical seperation between them (especially when viewing on search.cpan.org's box-style for fixed-width portions of POD). I'm not sure if this is really the best way to do it, and would like input on other potential methods.

----
I wanted to explore how Perl's closures can be manipulated, and ended up creating an object system by accident.
-- Schemer

Note: All code is untested, unless otherwise stated

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

[reply]
[d/l]
[select]
      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]
Re: Documenting Thrown Exceptions
by adrianh (Chancellor) on Jul 11, 2003 at 18:19 UTC

    I don't have a strict policy myself. Since POD is basically a free-form text language I just do whatever reads best in context. As well as what you outlined some other structures I use are:

    • List the exceptions thrown by themodule in a separate "Exceptions" section - useful if their are common exceptions thrown by many methods.
    • Use a list rather than a preformatted text section - useful if your exception descriptions are complex.
    • Use a separate document. I often have a single module that defines all the exceptions I use in my application (I like Exception::Class). I document all exceptions here and reference from the other modules. Gives you the advantage of having a single reference point.
[reply]
Re: Documenting Thrown Exceptions
by lachoy (Parson) on Jul 11, 2003 at 18:31 UTC

    Stephen Adkins was working on (and IIRC finished, at least to a good working point) a similar project for Perl code. I don't think he's got a project home page for it but you can browse the source and hopefully gain some illumnation.

    Chris
    M-x auto-bs-mode

[reply]

Back to Seekers of Perl Wisdom