> 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._
Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains ten additional commits since the last revision: - feedback: avoid com.sun.tools.javac.util.List - Improve a comment - feedback: typo and out-of-place method - Merge branch 'master' into 8304135 - Merge branch 'master' into 8304135 - Extract getActualMethod - Impose (almost) legacy order on implemented methods The legacy order is generated by an application of Utils.overriddenMethod followed by application of Utils.addSuperInterfaces. - Fix errors reported by jcheck - Initial commit ------------- Changes: - all: https://git.openjdk.org/jdk/pull/14221/files - new: https://git.openjdk.org/jdk/pull/14221/files/2cbe1bd1..1aed79fa Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=14221&range=02 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=14221&range=01-02 Stats: 46062 lines in 602 files changed: 38456 ins; 5824 del; 1782 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
