For an overriding or implementing method, Javadoc can inherit omitted documentation automatically. Use {@inheritDoc} when you want inherited text at a particular place or want to combine it with method-specific wording. The result depends on the method relationship, which comment parts are missing, the available ancestor comments, and the JDK version.
When Javadoc inherits method comments
Comment inheritance applies when a method overrides a superclass method, overrides a superinterface method, or implements an interface method. It does not apply to constructors, fields, or nested classes.
Under the JDK 26 standard-doclet specification, applicable documentation items omitted from an overriding method’s comment are treated as inherited. This can include the main description, parameter and return documentation, and documentation for thrown exceptions, subject to the rules for the method and the exceptions it declares. The overriding declaration determines which items are missing; do not assume every tag from an ancestor will automatically appear.
An “Overrides” or “Specified by” heading and a link to a related method indicate a relationship. They can appear even when no comment text was inherited.
Choose omission or explicit insertion
| Approach | Use it when | What to know |
|---|---|---|
| Omit applicable comment parts | The inherited documentation is suitable as-is. | The standard doclet can supply missing items for an overriding method under the inheritance rules. |
Use {@inheritDoc} |
You want to place inherited text deliberately, or surround it with method-specific wording. | Use it in the main description or the description for @param, @return, or @throws. The corresponding part must exist in the selected inherited comment, or Javadoc reports an error. |
Place inherited text with {@inheritDoc}
For example, a method can add its own context before inherited description text:
/** Handles a cached request before delegating.
* {@inheritDoc}
*/
@Override
public Result handle(Request request) { ... }The example assumes that handle overrides or implements a method whose comment has a main description available to inherit. If that matching part is absent, the tag is an error rather than an instruction to invent documentation.
Rank #2
The tag can also be used in supported block-tag descriptions:
/** {@inheritDoc}
* @param request {@inheritDoc}
* @return {@inheritDoc}
* @throws IOException {@inheritDoc}
*/Each use needs a corresponding inherited part. Use method-specific text instead when a parameter, result, or exception needs clarification that the ancestor’s wording does not provide.
Free tools Windows power users keep installed
One-click scans. No signup required.
How Javadoc chooses an ancestor
The unqualified {@inheritDoc} asks Javadoc to search relevant superinterfaces and superclass ancestry according to the standard doclet’s specified traversal. It is not safe to assume the superclass always wins when several ancestors provide documentation.
Since JDK 22, the tag can name a supertype explicitly: {@inheritDoc S}. Use this form when you need to identify which superclass or superinterface supplies the text. The named type must be a valid supertype from which the method is overridden; otherwise Javadoc reports an error. The syntax is specified in the JDK 25 standard-doclet specification.
Rank #4
Check source availability when text is missing
Javadoc needs access to the source file containing the inherited method’s comment. If that file is not on the Javadoc source path, the comment may not be available to copy. Check the source-path configuration as well as the method relationship and the matching comment part.
The comment formats do not have to match: Java’s official Markdown documentation guidance says a Markdown comment can inherit from a comment in another format.
Best Value
Quick troubleshooting checklist
- No text appears: Confirm the method actually overrides or implements an ancestor method, and that the ancestor’s source file is available on the Javadoc source path.
- Javadoc reports an inheritDoc error: Check that the corresponding main description, parameter, return, or throws description exists in the inherited comment.
- The text came from an unexpected ancestor: Review the hierarchy and documented interfaces; use
{@inheritDoc S}on JDK 22 or later when you need to specify a valid source type. - You expected inheritance for a non-method member: These method-comment inheritance rules do not cover constructors, fields, or nested classes.
The normative behavior is described in the JDK 26 standard-doclet specification.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
