Bug ID: JDK-8285368 Overhaul doc-comment inheritance

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

JDK 22	Other
22 b05Fixed	naResolved

This is an umbrella for a number of issues related to inheritance of doc comments. Those issues are linked to from this issue.

Many of those issues require a spec change [^1]. Those spec changes are so intertwined, that we think that it makes sense to file a single CSR (of this umbrella) to address them all as a single spec change.

** The list of linked issues is live: issues can be added or removed from this list. **

[^1]: https://docs.oracle.com/en/java/javase/18/docs/specs/javadoc/doc-comment-spec.html

Fix was pushed while main bug was targeted to 21. Resetting the main bug to fixed in 22 and copying the Robo Duke entry here.
28-06-2023
Changeset: 3e0bbd29 Author: Pavel Rappo <prappo@openjdk.org> Date: 2023-06-15 17:47:41 +0000 URL: https://git.openjdk.org/jdk/commit/3e0bbd290c534b0f9729c54cd45308d505907797
28-06-2023
A pull request was submitted for review. URL: https://git.openjdk.org/jdk/pull/14357 Date: 2023-06-07 14:19:16 +0000
07-06-2023
Thanks for working on javadoc comment inheritance. It's not easy. I had many struggles with comment inheritance while working on the spec for the Java Collection Framework. Too often I ran into various bugs, but also I recognized the limitations of comment inheritance in general - there were many cases where comment inheritance was almost, but only almost, what I wanted, and the result was giving up and resorting to copypasta which you can probably still see in java.util. today. I recall musing that java didn't offer multiple inheritance of code (too hard?!), but did offer multiple inheritance of spec!
11-05-2022

CSR :	JDK-8287152 - Overhaul doc-comment inheritance
Relates :	JDK-8296807 - Provide style for examples and streamline referencing JLS in doclet specification
Relates :	JDK-8295800 - When searching documentation for an exception, don't jump over methods that don't mention that exception
Relates :	JDK-6376959 - Algorithm for Inheriting Method Comments seems to go not as documented
Relates :	JDK-8005622 - Inherited Javadoc missing @throws
Relates :	JDK-8287100 - [spec] Clean up terminology regarding doc comment descriptions.
Relates :	JDK-8002153 - [doclint] {@inheritDoc} should check for docs to be inherited
Relates :	JDK-6934301 - Support directed inheriting of class comments with @inheritDoc
Relates :	JDK-8309964 - Use directed inheritDoc for javax.lang.model API
Relates :	JDK-8300517 - Refactor VisibleMemberTable (method members)