The {@inheritDoc} tag allows you to easily add new documentation before or after the inherited
documentation, but its effectiveness depends on how the original documentation was written. For example, if
the previous method's original @return comment was
@return The value last set, or null if it has not been set.
then the additional documentation results in a less than clear description:
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 comment 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 comment 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 inheriting 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 inherit 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 methodso if you don't automatically
inherit the comment the exception won't 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 documented 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 inheriting the associated @throws
comment, the problem with inheriting inapplicable @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 method. Rather than trying to automatically inherit the doc comments for unchecked 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 document that your method will
still throw IllegalArgumentException when it's parent would: