Java Reference
In-Depth Information
19.3. Inheriting Method Documentation Comments
If no doc comment is given for an inherited method, the method "inher-
its" the doc comment from the supertype. This is often quite enough, es-
pecially when a class implements an interfacemethods in the implement-
ation often do nothing more than what the interface specifies, or at least
nothing that belongs in a doc comment. It would be inconvenient, to say
the least, if you had to duplicate all the doc comments from an interface
or superclass to the class that defines the overriding method.
You should put in an explicit comment when you are inheriting doc com-
ments so that someone reading your code doesn't think that you forgot
to document the method, for example:
// inherit doc comment
public void dwim() throws IntentUnknownException {
// ...
}
While overriding an interface method might not require any changes to
the documentation, there is a good chance that overriding a superclass
method involves changes to the method contractsuch as weakening the
precondition on a parameter, strengthening the postcondition on a return
value, or reducing the types of exception that can be thrown. To make it
easier to change only those parts of the documentation that need chan-
ging, the block tags define separate entities that can be inherited inde-
pendently:
•
The main doc comment for the method is known as the
body com-
ment.
If you don't provide a body comment you will inherit the
complete body comment from the supertype. If you provide any
text as a body comment, then you won't inherit any part of the
supertype's body comment.
•
Each
@param
comment is inherited independently, based on the
name of the parameter. If you don't provide an
@param
comment
