Summary

Improve method documentation inheritance.

Problem

1. The documentation comment specification for the standard doclet poorly specifies documentation inheritance.

   The structure of inheritable elements and relationships between them are left to reader's intuitions.

2. The javadoc tool implements Method Comments Algorithm differently from how the documentation comment specification for the standard doclet specifies it.

   Although neither the expected nor the actual behavior is ideal, each has a good trait that the other does not.

3. Documentation inheritance lacks control.

   Regardless of a particular automatic algorithm, there will always be a case where it does a wrong thing.

Solution

1. To improve the specification, clarify the scope and rules of inheritance for individual elements.

   Clarify that:

   • /** {@inheritDoc} */ explicitly inherits only the main description,
   • @throws X {@inheritDoc} inherits all the tags describing the X exception type, not just some of them,
   • information for a method parameter, formal or type, is inherited by the parameter position, not by parameter name, to address possible parameter renaming among overrides

2. To reconcile the expected behavior with the actual behavior of Method Comments Algorithm, re-specify it and re-implement it in the javadoc tool.

   The proposal is to prefer a superclass to a superinterface, unless the superclass is java.lang.Object, in which case prefer a superinterface.

   While that proposal generally preserves the current behavior -- to prefer a superclass to a superinterface -- it also recognizes that any documentation -- even of a superinterface -- is more specific than that of java.lang.Object.

   To illustrate that change, we'll use diagrams. A diagram depicts an inheritance hierarchy. An edge points from a subtype to a supertype. Square brackets [ ] depict a class, parentheses ( ) depict an interface. Asterisk * marks the java.lang.Object class.

   The search order can be traced by following the sequence of integers, starting from 1. A class or an interface marked with 1 is searched first, with 2 is searched second, and so on.

   Let's consider two cases of a method that inherits documentation.

   1. The method is declared in a class.

      The current expected behavior is as follows:

                  (5)
                   ^
         *        /
        [7] (3) (4)
         ^   ^   ^
          \  |  /
           \ | /
            [6] (2)
             ^   ^
             |  /
             | /
            [1]

      The current actual behavior is as follows:

                  (6)
                   ^
         *        /
        [3] (4) (5)
         ^   ^   ^
          \  |  /
           \ | /
            [2] (7)
             ^   ^
             |  /
             | /
            [1]

      This proposal is to change the behavior as follows:

                  (5)
                   ^
         *        /
        [7] (3) (4)
         ^   ^   ^
          \  |  /
           \ | /
            [2] (6)
             ^   ^
             |  /
             | /
            [1]

   2. The method is declared in an interface.

      The current expected behavior is as follows:

        (3) (4)
         ^   ^
          \ /
          (2) (5)
           ^   ^
            \ /
            (1)

      Currently, the specification does not mention methods whose signature is override-equivalent to the signature of a public overridable method in java.lang.Object -- of which there are three: equals, hashCode, and toString, so java.lang.Object is never visited and, hence, is not on the diagram.

      However, the current actual behavior is to treat interfaces as if they had java.lang.Object as their superclass. Combined with preferring a superclass to a superinterface, the search short-circuits on the first interface's "superclass", java.lang.Object, which means that for the three relevant methods superinterfaces are not considered:

        (4) (5)
         ^   ^
          \ /
          (3) (6)
           ^   ^
            \ /
            (1)
             |
             v
            [2]
             *

      This proposal is to change the behavior as follows:

        (3) (4)
         ^   ^
          \ /
          (2) (5)
           ^   ^
            \ /
            (1)
             |
             v
            [6]
             *

      This change to the algorithm is backwards incompatible, but its scope is limited to the three public overridable methods of java.lang.Object and any unwanted differences in the generated documentation can be corrected by using directed inheritance, which is also introduced in this CSR below.

3. To control documentation inheritance as required, allow directed inheritance.

   Directed inheritance allows @inheritDoc to provide a supertype:

         {@inheritDoc <class-or-interface>}

   with the semantics that the inheritor gets documentation of the specified supertype, which in turn might inherit its documentation.

   While it has always been possible to copy-paste the desired documentation explicitly rather than inherit it, unlike this proposal, it's suboptimal (Don't Repeat Yourself) and lossy: potentially useful information on inheritance source is missing.

Specification

See the attached specification-v3.patch and api-v3.patch files. The latter is no different from api-v2.patch and added for clarity, to reflect the overall proposal revision change.