19.2.13. {@inheritDoc}
The {@inheritDoc} tag copies a documentation comment from the supertype. This is discussed in the
next section.
19.3. Inheriting Method Documentation Comments
If no doc comment is given for an inherited method, the method "inherits" the doc comment from the
supertype. This is often quite enough, especially when a class implements an interfacemethods in the
implementation 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 comments 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
changing, the block tags define separate entities that can be inherited independently:
The main doc comment for the method is known as the body comment. 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 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 superinterface 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.
*/