[jdom-interest] Exception documentation

[Elliotte Rusty Harold]

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/   |
+----------------------------------+---------------------------------+