Java Reference
In-Depth Information
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: