JDK-8291803 : Detect simple overrides better
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 20
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2022-08-03
  • Updated: 2024-01-15
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.
Other
tbdUnresolved
Related Reports
Blocks :  
JDK-8291869 - Match exceptions using types of javax.lang.model, not strings
Blocks :  
JDK-8287796 - Stop auto-inheriting documentation for subclasses of exceptions whose documentation is inherited
Relates :  
JDK-8296607 - Review and specify no-spec-change overrides
Relates :  
JDK-8187386 - Do not generate javadoc for overridden method with no spec change
Relates :  
JDK-8294377 - Prepare to stop auto-inheriting documentation for subclasses of exceptions whose documentation is inherited
Description
A "simple override" is a JavaDoc lingo for an overriding method that does not change the spec provided by the overridden method in any way.

Currently, "simple overrides" are both underdetected and detected incorrectly. Underdetection (i.e. a false negative) happens when one or more inheritable block tags consist of `{@inheritDoc}`. Incorrect detection happens when omitted `@throws X {@inheritDoc}` tags are assumed to be inherited, which they are not, unless `X` is listed in the `throws` clause.
Comments
In regard to my previous comment, resolving JDK-8287796 before this caused fewer issues than were initially anticipated. Moving this to JDK 21.
28-11-2022
This issue should be resolved before JDK-8287796. Otherwise, there will be extraneous differences in the resulting documentation.
03-08-2022
While looking at this, I discovered VisibleMemberTable.overridingSignatureChanged. I wonder if Utils.isSimpleOverride and VisibleMemberTable.overridingSignatureChanged could be combined behind a convenient internal API.
03-08-2022