JDK-8157000 : Do not generate javadoc for overridden method with no spec change
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 9
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2016-05-14
  • Updated: 2022-11-08
  • Resolved: 2017-10-20
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 10
10 b29Fixed
Related Reports
CSR :  
JDK-8187386 - Do not generate javadoc for overridden method with no spec change
Duplicate :  
JDK-8205590 - API Documentation should include one more tab for "added methods"
Relates :  
JDK-8190436 - Bug in VisibleMemberMap, including non-deterministic behavior
Relates :  
JDK-8219147 - Javadoc should expose covariant return type overrides
Relates :  
JDK-8029891 - Deadlock detected in java/lang/ClassLoader/deadlock/GetResource.java
Relates :  
JDK-8198890 - The standard doclet incorrectly produces wrong method signatures in certain cases.
Relates :  
JDK-8296607 - Review and specify no-spec-change overrides
Relates :  
JDK-8249070 - @inheritDoc does not work if standalone
Relates :  
JDK-8189845 - Fix for 8157000 causes significant performance regression
Relates :  
JDK-8264217 - Overriding method with absent spec is not mentioned as overriding in the JavaSE class specification
Relates :  
JDK-8199281 - Broken link in nav bar "Summary: ... METHOD" when it points to inherited methods of super class.
Relates :  
JDK-8271485 - Javadoc "Method Summary" table is misaligned if overridden JDK method has {@inheritDoc} tag
Relates :  
JDK-8037423 - @treatAsPrivate should hide the member for sub classes
Sub Tasks
JDK-8192926 :  
Release Note: Overriding Methods That Do Not Change the Specification - Closed
Description
By default javadoc  is generated for a method if it overrides a method defined in its supertype.

When a method is overridden with no change in semantic behavior, javadoc currently lists it in the primary method summary just with @inheritdoc.  It is not that useful.   When many methods are overridden, including inherited docs for these methods in the primary method summary is just noise.  Keeping them in "Methods inherited from ..." section would be adequate.

Perhaps javadoc should not bother listing overridden methods that do not have any comment provided to document any change of semantic behavior.
Comments
Filed JDK-8189845 to track the performance regression.
24-10-2017
I was sort of expecting it, to compute the visibility, there are more accesses to a javadoc internal data structure VisibleMemberMap, there are plans to improve this, let me try to find an interim performance solution.
23-10-2017
This change seems to have more than doubled the execution time of javadoc in the jdk build. On my machine, the docs-jdk-api-javadoc target has gone from around 2 minutes to 5:40. Is this expected?
23-10-2017
URL: http://hg.openjdk.java.net/jdk10/master/rev/2ea4edfdef8e User: ksrini Date: 2017-10-20 03:32:14 +0000
20-10-2017
http://mail.openjdk.java.net/pipermail/javadoc-dev/2017-September/000312.html
22-09-2017
Many times you are changing implementation details not specified behaviour. If anything about the behaviour changes then it should certainly be documented. The "Methods inherited from XXX " section lists methods for which both the implementation and specification are inherited from XXX. It may be useful to also have something like "Method specifications inherited from XXX" for those methods which have been overridden but not in a way that changes any part of the specification. Arguably this is of limited use as usually we override to have some impact on behaviour that we would want to document. The motivating case here was a bad starting point: class Properties extends Hashtable. The Properties API is not a logical extension of the Hashtable API and inheritance should never have been used - but that decision was made 20 years ago. The implementation change was to make Properties delegate the Hashtable methods to a separate Hashmap implementation to improve performance and avoid deadlock scenarios. Having all the Hashtable methods appear explicitly in the Properties javadoc is undesirable as it gives them too much visibility, when we would prefer that people didn't even realize they exist. Having them not appear at all in the javadoc, as was the case when @hidden was applied, is also undesirable as (like it or not) they do exist and can be called and so must be documented as existing. Having the overridden methods appear in the "Methods inherited from ..." list would be wrong as they do not use the implementation from the superclass. So we need a new short form to say "these methods, specified in XXX, have been overridden, but not in a way that changes their specification".
16-05-2016
On the one hand, I wonder why tests are being overridden if there is no change in the semantic behavior (why override it if you are not changing the behavior) and if the behavior is being changed, why not document the change, but on the other hand, it is conceivable the (change in) behavior is being documented elsewhere. For example, a class comment could contain text that applies to all methods, such as "all methods in this class print tracing information before calling the overridden method". It would be interesting to investigate how many methods in the Java SE API would be affected by such a change. Without commenting whether it would be desirable or not, docs that prefer that these methods should be documented could use an explicit /** {@inheritDoc} */ comment -- although it would be an explicit change to make this behavior opt-in.
15-05-2016