JDK-8258429 : Refine inheritDoc tag effect for certain user-visible method signature changes
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • Submitted: 2020-12-15
  • Updated: 2020-12-18
  • Resolved: 2020-12-18
Related Reports
Duplicate :  
Relates :  
Relates :  
Description
Currently if a subclass concretely overrides an abstract method of its parent class and its method documentation is as

/**
 * {@inheritDoc}
 */

then the subclass method's javadoc will end up in the "Methods declared in class packageName.superclassName" section of the subclass javadoc instead of in the primary method listing. In this case the only way to know that the class overrode the method is to note that the class is concrete whereas its parent class is abstract. If there are several abstract classes in a hierarchy it can be impossible to determine which class overrode the method. Knowing which class(es) actually implement(s) the abstract method may be information valuable to a developer.

In general it would be good if inheritDoc were to automatically generate verbiage for an overriding method for changes in abstractness, access modifiers (protected to public), finality (non-final to final), and any other appropriate user-visible method signature changes.
Comments
All conditions mentioned in this issue have been included in JDK-8223607.
18-12-2020

Should specifically include checks for * change of access * change final/non-final * change abstract/non-abstract
15-12-2020

For the record, the relevant code is Utils.isSimpleOverride at about Utils.java:1577. It does not look like we check covariant override, at least there. 3 replies From Slack: Jonathan Gibbons 2 hours ago covariant returns are handled in usages of that method VisibleMemberTable:587 (edited) Jonathan Gibbons 2 hours ago That looks like the place to improve the "is it different" check Jonathan Gibbons 2 hours ago the code determines and uses covariantReturn .. it could also determine modifiersChanged (filtering out native and synchronized)
15-12-2020