Java Reference
In-Depth Information
be documented and that is wrong. But then consider, for example, an
interface with optionally implemented methods that declare that they
throw
UnsupportedOperationException
. This runtime exception is documen-
ted by an
@tHRows
comment. If the comment is automatically inherited
then even if a particular class's implementation supports the operation
and so never throws the exception, the exception will be documented as
being thrownwhich, again, is wrong.
By requiring that exceptions be listed in the
tHRows
clause before inher-
iting the associated
@throws
comment, the problem with inheriting inap-
plicable
@throws
comments is avoided. However, this promotes a style of
programming where runtime exceptions are listed in a method's
tHRows
clause, which goes against standard practice. We recommend that you
continue to list only checked exceptions in the
tHRows
clause of a meth-
od. Rather than trying to automatically inherit the doc comments for un-
checked exceptions, we suggest that you manually rewrite the
@tHRows
comment, but use
{@inheritDoc}
to avoid the need to manually copy the
exception description. For example, you can use the following to docu-
ment that your method will still throw
IllegalArgumentException
when it's
parent would:
@throws IllegalArgumentException {@inheritDoc}
The onus is still on you to remember that unchecked exceptions must
be manually documented in this way.
