RFR: JDK-8302019: Clarify Elements.overrides [v5]

[Pavel Rappo]

On Thu, 25 Jan 2024 18:12:52 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> Explicitly discuss and test handling of an interface declaring methods that "override" public methods on java.lang.Object.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Refine javadoc.

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

> 692:      * public} method of {@link Object java.lang.Object}, this method treats
> 693:      * any such interface methods as overriding the corresponding {@code
> 694:      * Object} method; example:

1. It doesn't help comprehension when "method" means two things in a sentence at the same time: (i) ExecutableElement that models a method and (ii) the method the doc comment belongs to (i.e. Elements.overrides) and that takes ExecutableElement as its argument(s). 
I understand that it's always tricky in `javax.lang.model` domain, but still wonder if the sentence can be tweaked a bit.

2. "example:"? Would "for example:" be better?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17564#discussion_r1466804259