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/formats/html/HtmlDocletWriter.java
line 291:
> 289: * @param dl the content to which the method information will be
> added
> 290: */
> 291: private void addMethodInfo(ExecutableElement method, Content dl) {
It's not anything you've changed, and not part of the problem you're fixing,
but this doesn't feel like it belongs on `HtmlDocletWriter`. But that's
another story of different architectural Technical Debt.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14221#discussion_r1214973272
