Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8187386

Do not generate javadoc for overridden method with no spec change

    XMLWordPrintable

Details

    • low
    • Hide
      This is an opt-in new feature in the standard doclet.
      We should investigate whether we need to clarify the compatibility (TCK) requirements for an implementation to choose to override or not override API methods without changing the specification.
      Show
      This is an opt-in new feature in the standard doclet. We should investigate whether we need to clarify the compatibility (TCK) requirements for an implementation to choose to override or not override API methods without changing the specification.

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

      Attachments

        Issue Links

          Activity

            People

              ksrini Kumar Srinivasan
              mchung Mandy Chung
              Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: