|
CSR :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
|
|
Relates :
|
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.
|