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 ", which will replace the previous list, "Methods inherited from ".

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.