On Tue, 30 May 2023 14:07:05 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._ This pull request has been closed without being integrated. ------------- PR: https://git.openjdk.org/jdk/pull/14221
