RFR: 4397513: (reflect) InvocationHandler.invoke javadoc slightly misleading for "method" parameter

[Alan Bateman]

On Wed, 22 Oct 2025 21:41:49 GMT, Chen Liang <liach at openjdk.org> wrote:

> The `method` parameter documentation for `InvocationHandler::invoke` does not indicate that it may be one of the 3 Object methods `hashCode`, `equals`, or `toString`. This doc-only improvement clarifies that, links to the Proxy section about declaring class selection, and updates the "the interface method" occurrences to be "the invoked method" to reflect the method may be from `Object`.

src/java.base/share/classes/java/lang/reflect/InvocationHandler.java line 63:

> 61:      * declared in one of the proxy interfaces or a superinterface of them.
> 62:      * See also the {@linkplain Proxy##duplicate-methods "Methods Duplicated in
> 63:      * Multiple Proxy Interfaces"} section in {@code Proxy}.

The proposed wording looks okay for when a method is invoked on a proxy instance. 

InvocationHandler is not strictly tied to Proxy. I'm just wondering if the we should qualify this so that the text is in the context invoking a method on the proxy object. I'm also wondering if it should be moved to the interface description to avoid multi sentence parameter description, e.g. "When invoked on a proxy object, the method ...".  Up to you but I suspect there are wider usages of this interface.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27943#discussion_r2454626456