RFR: 8304135: Introduce unified overridden methods query [v3]

[Pavel Rappo]

On Fri, 9 Jun 2023 11:55:27 GMT, Pavel Rappo <prappo at 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 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

One thing that bothers me after extensive analysis of JDK API documentation differences caused by this PR is loss of information. Before this PR, JavaDoc documented more methods on a class or interface page than there were member methods in that class or interface.

For example, consider `AbstractCollection`. It does not declare `equals`, but it extends `Object` and implements `Collection`, each of which declare and document `equals()`. According to Java Language Specification (JLS), `AbtractCollection` inherits `Object.equals`, but doesn't inherit `Collections.equals`. So, as far as method members go, there's no place for `Collection.equals` among members of `AbstractCollection`. Yet, VMT for AbstractCollection stored both of them. 

In the new VMT there's no place for non-members. That observation alone suggests that JavaDoc view is not the same as JLS view. While JavaDoc shouldn't contradict JLS or mislead the reader, it should also help the reader to discover and access relevant information beyond that immediately available from the language model. Before we figure out how to do that, **I'm parking this PR**.

I note that all the tests are green: https://cr.openjdk.org/~prappo/8304135/tests.txt

-------------

PR Comment: https://git.openjdk.org/jdk/pull/14221#issuecomment-1584469209