Makes sense. I stumbled over that myself from time to time but it didn't really bother me so much to take action.
On 26.09.2009 14:41:37 Alexander Kiel wrote: > Hi, > > why didn't our code style allow unchecked exceptions or subclasses of > thrown exceptions in Javadoc? > > From checkstyle-5.0.xml: > > <module name="RedundantThrowsCheck"> > <property name="allowSubclasses" value="false"/> > <property name="allowUnchecked" value="false"/> > <property name="severity" value="warning"/> > </module> > > From "J. Bloch: Effective Java, Second Edition" [1] page 252: > > >Use the Javadoc @thows tag to document each unchecked exception > >that a method can throw, but do not use the throws keyword to > >include unchecked exceptions in the method declaration. > > Every good code I know, documents unchecked exceptions. Take the Java > Collections API. Every possible ClassCastException or > NullPointerException is documented. > > Another quote from J. Bloch: > > >A well-documented list of unchecked exceptions that a method > >can throw effectively describes the preconditions for its > >successful execution. It is essential that each method's > >documentation describe its preconditions [...] > > I think that everyone can agree with the statements J. Bloch made. So I > would strongly vote to allow documenting unchecked exceptions. > > > The second point is not allowing subclasses of exceptions in Javadoc. I > don't use this very often, but I have just one example in my mind where > this makes sense. If you have a look into > java.io.DataInputStream#readByte(), there are both IOException and > EOFException documented. EOFException is a subclass of IOException. As > you know a normal InputStream.read() returns -1 at EOF but readByte() > doesn't. So it's worth documenting that readByte() is throwing a > EOFException instead. > > So I would also vote allowing subclasses. > > > Best Regards > Alex > > [1]: <http://www.amazon.com/dp/0321356683/> > > -- > e-mail: alexanderk...@gmx.net > web: www.alexanderkiel.net > Jeremias Maerki
