On Fri, 2 Jun 2023 12:10:45 GMT, Pavel Rappo <pra...@openjdk.org> 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 1026: > 1024: * Translates the provided class or interface to a type given its > subtype. > 1025: * > 1026: * The correctness relies of no more than 1 parameterization from > JLS. (TODO link the correct section) typo? `of` -> `on` ? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java line 1366: > 1364: } > 1365: // Documented annotations, other than java.lang.Override, added > anywhere in the method signature > 1366: var JAVA_LANG_OVERRIDE = > elements().getTypeElement("java.lang.Override"); Interesting observation... (not wrong) ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/14221#discussion_r1214916777 PR Review Comment: https://git.openjdk.org/jdk/pull/14221#discussion_r1214916118