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.
|