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

Do not generate javadoc for overridden method with no spec change

    Details

    • Type: Enhancement
    • Status: Resolved
    • Priority: P4
    • Resolution: Fixed
    • Affects Version/s: 9
    • Fix Version/s: 10
    • Component/s: tools

      Description

      By default javadoc is generated for a method if it overrides a method defined in its supertype.

      When a method is overridden with no change in semantic behavior, javadoc currently lists it in the primary method summary just with @inheritdoc. It is not that useful. When many methods are overridden, including inherited docs for these methods in the primary method summary is just noise. Keeping them in "Methods inherited from ..." section would be adequate.

      Perhaps javadoc should not bother listing overridden methods that do not have any comment provided to document any change of semantic behavior.

        Issue Links

          Activity

          Hide
          jjg Jonathan Gibbons added a comment - - edited
          On the one hand, I wonder why tests are being overridden if there is no change in the semantic behavior (why override it if you are not changing the behavior) and if the behavior is being changed, why not document the change, but on the other hand, it is conceivable the (change in) behavior is being documented elsewhere. For example, a class comment could contain text that applies to all methods, such as "all methods in this class print tracing information before calling the overridden method".

          It would be interesting to investigate how many methods in the Java SE API would be affected by such a change.

          Without commenting whether it would be desirable or not, docs that prefer that these methods should be documented could use an explicit /** {@inheritDoc} */ comment -- although it would be an explicit change to make this behavior opt-in.
          Show
          jjg Jonathan Gibbons added a comment - - edited On the one hand, I wonder why tests are being overridden if there is no change in the semantic behavior (why override it if you are not changing the behavior) and if the behavior is being changed, why not document the change, but on the other hand, it is conceivable the (change in) behavior is being documented elsewhere. For example, a class comment could contain text that applies to all methods, such as "all methods in this class print tracing information before calling the overridden method". It would be interesting to investigate how many methods in the Java SE API would be affected by such a change. Without commenting whether it would be desirable or not, docs that prefer that these methods should be documented could use an explicit /** {@inheritDoc} */ comment -- although it would be an explicit change to make this behavior opt-in.
          Hide
          dholmes David Holmes added a comment -
          Many times you are changing implementation details not specified behaviour. If anything about the behaviour changes then it should certainly be documented.

          The "Methods inherited from XXX " section lists methods for which both the implementation and specification are inherited from XXX. It may be useful to also have something like "Method specifications inherited from XXX" for those methods which have been overridden but not in a way that changes any part of the specification.

          Arguably this is of limited use as usually we override to have some impact on behaviour that we would want to document. The motivating case here was a bad starting point: class Properties extends Hashtable. The Properties API is not a logical extension of the Hashtable API and inheritance should never have been used - but that decision was made 20 years ago. The implementation change was to make Properties delegate the Hashtable methods to a separate Hashmap implementation to improve performance and avoid deadlock scenarios. Having all the Hashtable methods appear explicitly in the Properties javadoc is undesirable as it gives them too much visibility, when we would prefer that people didn't even realize they exist. Having them not appear at all in the javadoc, as was the case when @hidden was applied, is also undesirable as (like it or not) they do exist and can be called and so must be documented as existing. Having the overridden methods appear in the "Methods inherited from ..." list would be wrong as they do not use the implementation from the superclass. So we need a new short form to say "these methods, specified in XXX, have been overridden, but not in a way that changes their specification".
          Show
          dholmes David Holmes added a comment - Many times you are changing implementation details not specified behaviour. If anything about the behaviour changes then it should certainly be documented. The "Methods inherited from XXX " section lists methods for which both the implementation and specification are inherited from XXX. It may be useful to also have something like "Method specifications inherited from XXX" for those methods which have been overridden but not in a way that changes any part of the specification. Arguably this is of limited use as usually we override to have some impact on behaviour that we would want to document. The motivating case here was a bad starting point: class Properties extends Hashtable. The Properties API is not a logical extension of the Hashtable API and inheritance should never have been used - but that decision was made 20 years ago. The implementation change was to make Properties delegate the Hashtable methods to a separate Hashmap implementation to improve performance and avoid deadlock scenarios. Having all the Hashtable methods appear explicitly in the Properties javadoc is undesirable as it gives them too much visibility, when we would prefer that people didn't even realize they exist. Having them not appear at all in the javadoc, as was the case when @hidden was applied, is also undesirable as (like it or not) they do exist and can be called and so must be documented as existing. Having the overridden methods appear in the "Methods inherited from ..." list would be wrong as they do not use the implementation from the superclass. So we need a new short form to say "these methods, specified in XXX, have been overridden, but not in a way that changes their specification".
          Show
          ksrini Kumar Srinivasan added a comment - http://mail.openjdk.java.net/pipermail/javadoc-dev/2017-September/000312.html
          Hide
          hgupdate HG Updates added a comment -
          URL: http://hg.openjdk.java.net/jdk10/master/rev/2ea4edfdef8e
          User: ksrini
          Date: 2017-10-20 03:32:14 +0000
          Show
          hgupdate HG Updates added a comment - URL: http://hg.openjdk.java.net/jdk10/master/rev/2ea4edfdef8e User: ksrini Date: 2017-10-20 03:32:14 +0000
          Hide
          erikj Erik Joelsson added a comment -
          This change seems to have more than doubled the execution time of javadoc in the jdk build. On my machine, the docs-jdk-api-javadoc target has gone from around 2 minutes to 5:40. Is this expected?
          Show
          erikj Erik Joelsson added a comment - This change seems to have more than doubled the execution time of javadoc in the jdk build. On my machine, the docs-jdk-api-javadoc target has gone from around 2 minutes to 5:40. Is this expected?
          Hide
          ksrini Kumar Srinivasan added a comment - - edited
          I was sort of expecting it, to compute the visibility, there are more accesses to a javadoc internal data structure VisibleMemberMap, there are plans to improve this,
          let me try to find an interim performance solution.
          Show
          ksrini Kumar Srinivasan added a comment - - edited I was sort of expecting it, to compute the visibility, there are more accesses to a javadoc internal data structure VisibleMemberMap, there are plans to improve this, let me try to find an interim performance solution.
          Hide
          ksrini Kumar Srinivasan added a comment -
          Filed JDK-8189845 to track the performance regression.
          Show
          ksrini Kumar Srinivasan added a comment - Filed JDK-8189845 to track the performance regression.

            People

            • Assignee:
              ksrini Kumar Srinivasan
              Reporter:
              mchung Mandy Chung
            • Votes:
              0 Vote for this issue
              Watchers:
              8 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: