On Fri, 2 Jun 2023 12:10:45 GMT, Pavel Rappo <[email protected]> wrote:
>> 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 five additional > commits since the last revision: > > - 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 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java line 1015: > 1013: // will be computed once the complete sequence is > available > 1014: var simpleOverride = false; > 1015: result = result.append(new > OverrideData(toDeclaringType(s, `append` is *horrible* on `javac.util.List` Unless there is a string reason to be using it, you should probably be using plain old collection Lists, like `ArrayList` or `List.of`. If you're using `javac.util.List` because you're calling javac internal functionality that requires that kind of List, then your usage should be in methods in `WorkArounds`, which is intended to the the only doclet class that accesses javac internal methods and types. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/14221#discussion_r1215039898
