[jdom-interest] Exception documentation

[Jason Hunter]

Definitely, it's good style.  If you're willing to send in a patch, I'll
check it in right away.

-jh-

Elliotte Rusty Harold wrote:
> 
> We've been inconsistent about reporting runtime exceptions like
> IllegalNameException in both method signatures and JavaDoc comments. For
> example, in the Element class the setName() method is declared like so:
> 
>      * @throws IllegalNameException if the given name is illegal as an
>      *         Element name.
>      */
>     public Element setName(String name) {
> 
> However, the public constructors that all call setName() do not include
> an @throws clause for the same exception. Similar issues occur
> throughtout the JDOM packages.
> 
> I'd like to propose the following coding conventions:
> 
> 1. All methods that throw a JDOM-specific runtime exception such as
> IllegalNameException should include an @throws comment for that exception.
> 
> 2. All methods that throw a JDOM-specific runtime exception such as
> IllegalNameException should include that exception in their throws
> clause, even though the Java compiler does not require this.
> 
> I think this will make the JavaDoc and the code more completely
> descriptive. It should have absolutely no effect on the actual behavior
> of the classes and should not in any way break anybody's exisitng code.
> Thoughts? Comments?
> 
> --
> +-----------------------+------------------------+-------------------+
> | Elliotte Rusty Harold | elharo at metalab.unc.edu | Writer/Programmer |
> +-----------------------+------------------------+-------------------+
> |           The XML Bible, 2nd Edition (IDG Books, 2001)             |
> |             http://www.cafeconleche.org/books/bible2/              |
> |   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
> +----------------------------------+---------------------------------+
> |  Read Cafe au Lait for Java News:   http://www.cafeaulait.org/     |
> |  Read Cafe con Leche for XML News:  http://www.cafeconleche.org/   |
> +----------------------------------+---------------------------------+
> 
> _______________________________________________
> To control your jdom-interest membership:
> http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@yourhost.com