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.