RFR: 8174840: Elements.overrides does not check the return type of the methods [v2]

[Joe Darcy]

On Thu, 23 Jan 2025 13:56:35 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this PR to clarify the documentation of `Elements.overrides` through an `@apiNote`, this PR is essentially a doc-only change. This PR supersedes https://github.com/openjdk/jdk/pull/22244.
>> 
>> TIA.
>
> Nizar Benalla 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 seven additional commits since the last revision:
> 
>  - whitespace
>  - Update according to review comments.
>  - Merge remote-tracking branch 'upstream/master' into elements-api-note
>  - Respond to feedback around the wording.
>  - Respond to feedback. Using Jan's comment to not imply particular requirement on the implementation.
>  - (C) 2025
>  - Initial commit obtained from a cherry pick/squash of a now superseded PR.

src/java.compiler/share/classes/javax/lang/model/util/Elements.java line 784:

> 782:      * return types, and method modifiers specified in JLS {@jls 8.4.8.1} and {@jls 8.4.8.3},
> 783:      * although implementations of this method are allowed to implement these additional checks.
> 784:      *

I don't think the current wording conveys enough context for the reader. I suggest a structure like:

apiNote
This method must examines X, Y, and Z in determining whether one method overrides another. In addition, an implementation may have a stricter checking including  at properties A, B, and C as described in JLS ..."

HTH

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22920#discussion_r1978563468