Sometimes we get exceptions that are not described in Javadoc.
For instance, recently we're encountering java.lang.IllegalThreadStateException in NetBeans, which is thrown from ThreadReference.suspendCount(). See http://www.netbeans.org/issues/show_bug.cgi?id=105361.
But when I scan Javadocs for "IllegalThreadStateException", all I get is EventRequest.enable() and EventRequest.setEnabled(). So I would suppose that other methods should not throw it.

Thus I'm submitting this to improve the Javadoc and add the constraints under which the methods work.