Please review this change.
It turns out that JavaDoc's model for overriding and inheritance for methods is
simplistic. As a result, it fails to accommodate upcoming changes in the
"method comments algorithm" and the new feature called "directed documentation
inheritance".
This change aligns JavaDoc's model for overriding and inheritance for methods
with that of the Java Language Specification. The most important part of the
change pertains to overridden methods. The model now recognizes that
"overrides" is not a transitive relation: from the fact that A overrides B and
B overrides C, it does not necessarily follow that A overrides C. The model
also recognizes that "overrides" depends on three parameters, not two: the
method that overrides, the method that is being overridden, and the class where
the override takes place. For details, see the test that this change adds:
`TestMethodMembers.java`.
Additionally, the change provides a unified query for method overrides: be it
defined in a class or interface, be it abstract or concrete, an overridden
method can be queried through a single new API method in `VisibleMemberTable`:
public OverrideSequence overrideAt(ExecutableElement method)
That query accepts a method and returns a sequence of methods that the accepted
method overrides from the class or interface described by the instance of
`VisibleMemberTable` that the query has been called on. That sequence is
totally ordered and can be traversed in either direction.
It's quite remarkable that there are only 2 existing tests that required some
adjustment after the change. However, there are approximately 250 changed files
in the generated JDK API Documentation (i.e. the result of `make docs`). Most
of them are benign or beneficial (e.g. they fix a bug). However, there is at
least one that will need to be fixed after the upcoming but separate "directed
documentation inheritance" update: `java.util.concurrent.LinkedBlockingDeque`.
With this change, it takes the same time (as measured with `TIME(1)`) to run
the tests and produce JDK API documentation. Proper benchmarks will be done
later on.
---
_Meanwhile, I'll try to figure out a convenient way to attach diffs for JDK API
Documentation to this PR._
-------------
Commit messages:
- Fix errors reported by jcheck
- Initial commit
Changes: https://git.openjdk.org/jdk/pull/14221/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=14221&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8304135
Stats: 1736 lines in 20 files changed: 1146 ins; 417 del; 173 mod
Patch: https://git.openjdk.org/jdk/pull/14221.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/14221/head:pull/14221
PR: https://git.openjdk.org/jdk/pull/14221
