Documentation Comments - The Java Programming Language - page 720

for a parameter, then you'll inherit the @param comment from the
supertype.
• If no @return comment is specified then the @return comment from
the supertype is inherited.
• There are special rules for @tHRows comments, as discussed below.
If a method inherits doc comments from both a superclass and super-
interface the interface comment is used.
Often, the change to a doc comment only involves the addition of extra
information. For example, an overriding method might guarantee that it
never returns null , where the parent method could return null . To avoid
manually copying the doc comment from the supertype, you can use
the {@inheritDoc} tag to copy the doc comment from the supertype. The
{@inheritDoc} tag can appear either in the body comment or within any
of the block tags, and it copies the entire supertype's doc comment for
that entity. For example, the method that no longer returns null could
have a doc comment like this:
/**
* @return {@inheritDoc}
* This implementation never returns null.
*/
The {@inheritDoc} tag allows you to easily add new documentation be-
fore or after the inherited documentation, but its effectiveness depends
on how the original documentation was written. For example, if the pre-
vious 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 descrip-
tion: