Java Reference
In-Depth Information
Returns: The value last set, or null if it has not been set.
This implementation never returns null.
For the sake of clarity, it might be better to rewrite the entire doc com-
ment rather than try to augment it.
19.3.1. Inheriting
@tHRows
Comments
There is a special rule for inheriting
@throws
comments: An overriding
method only inherits the
@throws
comments for exceptions listed in its
throws
clause, and that are documented by the overridden method. For
example, if the original method has an
@throws
comment for
IOException
and the overriding method declares that it throws
IOException
, then the
comment is inherited. However, if the overriding method declares that
it throws
FileNotFoundException
(a subclass of
IOException
) then the com-
ment is not inherited because that exception type is not documented
by the overridden method. This restriction on when inheritance of the
@throws
comment occurs is necessary because automatically inheriting
@throws
comments is often the wrong thing to do. Unfortunately, not in-
heriting them can also be the wrong thing to do.
An overriding method can throw fewer checked exceptions than the
method it overrides, but not more. So automatically inheriting
@throws
comments for a checked exception that is not actually thrown would be
the wrong thing to do. For checked exceptions it makes sense to inher-
it the documentation comments only for those exceptions listed in the
throws
clause. They are, after all, the only checked exceptions that can
be thrown. So you inherit the comment if you still throw the exception
and you don't inherit the comment if you don't.
Runtime exceptions, which are not typically declared in the
throws
clause, add a twist to the situation. You usually want to inherit
@throws
comments for exceptions like
IllegalArgumentException
because what is
illegal for the method you override is typically illegal for your meth-
odso if you don't automatically inherit the comment the exception won't
