JDK-8187386 : Do not generate javadoc for overridden method with no spec change
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 10
  • Submitted: 2017-09-08
  • Updated: 2022-09-26
  • Resolved: 2017-09-13
Related Reports
CSR :  
Relates :  
Relates :  
Relates :  
Relates :  
Description
Summary
-------

Document more concisely those methods which simply override a method without
changing or adding to the specification in any way.

Problem
-------

There are about 1400 methods in the JDK sources that override a method in a supertype
without modifying the specification. For instance, in the case of java.util.Properties, all
the inherited methods from Map are just delegated to an encapsulated ConcurrentHashMap.
Such methods appear in the Summary and the Details sections of the class documentation,
cluttering it with no added value to the reader, since all the documentation is inherited
from the supertype. The number of such methods has grown over time, especially with
the introduction of default methods in interfaces in JDK 8.

Solution
--------
To improve the clarity of such class documentation, the standard doclet will identify those
methods described above, and categorize them along with inherited methods in the
lists at the end of the Summary table.

Specification
-------------

The methods that are overridden and which do not modify the API in any way will be 
determined by checking if the method has no documentation comment, or if the 
comment just contains the single inline tag, `{@inheritDoc}`.
These methods will only be listed in the Summary table along with inherited
methods, under a new heading "Methods declared in <supertype>",
which will replace the previous list, "Methods inherited from <supertype>".

This behavior will be controlled by a new javadoc command-line option

    --overridden-methods=details|summary

where a value of `details` is the current behavior and will be the default, and
`summary` will be to just list the relevant methods only in a list at the end of
the Summary table.



Comments
This somewhat relates to JDK-4167590 in the sense that `javadoc` should be economical with the volume of produced docs and not make reader's eyes to (unnecessarily) bleed.
31-08-2020

There's a weird corner case here. The behavior of the old javadoc when a javadoc comment is elided is to reproduce the inherited javadoc ***with any throws specs for unchecked exceptions removed*** (arguably a misfeature...) So the use of this flag will produce different specs, depending on whether detail or summary is chosen - only one will include the inherited unchecked exceptions. There's lots of code out there that ignored the subtlety with the old javadoc, and the --overriden-methods= will further confuse the issue, but few will care enough to worry as I am doing now.
08-12-2017

Moving to approved.
13-09-2017

Yes, I agree.
08-09-2017

I think there should be "old behavior" and "new behavior". That implies the header will change between "Methods inherited in ..." and "Methods declared in ..."
08-09-2017

Is the new footnote header an invariant, ie. with --overriden-methods = details old footnote and with summary the new footnote header ?
08-09-2017