RFR: 8263102: Expand documention of Method.isBridge [v3]

[Stuart Marks]

On Tue, 9 Mar 2021 19:13:24 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/reflect/Method.java line 589:
>> 
>>> 587:      * different return type, the virtual machine does not.
>>> 588:      * A
>>> 589:      * common case where covariant overrides are used is for a {@link
>> 
>> I think the example should be clearer because here, you don't show the code of EnumSet.clone().
>> I wonder if it's not easier if all the code is visible
>>   interface I {
>>     Object m();
>>   }
>>   class A implements I {
>>     String m() { return "hello"; }
>>   }
>> so you can explain that the VM do the dispatch on I::m()Object so the compiler has to insert a method A::m()Object,
>> the bridge method with this pseudo-code
>>   class A implements I {
>>     /* bridge */ Object m() { return m(); } // calls m()String
>>     String m()  { return "hello"; }
>>   }
>
> Hi Remi,
> 
> Thanks for the feedback. I did consider that kind of approach of an example from scratch. I judged referencing instances of bridge methods in the base module to be helpful to demonstrate it wasn't too esoteric of a feature in terms of it is something you, as a developer, may already have seen. Also, given the likely audience of the reading Class.isBridge, I didn't think a stand-alone example was warranted.

The prose description here and is still rather clumsy, though. If you're going to use EnumSet.clone() as an example, maybe run with that and list the methods directly instead of saying "EnumSet.clone() returns EnumSet rather than Object", be more explicit. Maybe something like the following:

The Object class has the method:
 clone()```
whereas the EnumSet class has this method:
<E> clone()```
>From the JVM's perspective, the second method doesn't override the first, because they have different return types. The Java compiler provides a proper override by inserting the following bridge method into the EnumSet class:
 clone()```
that simply calls the second method and returns its result.

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

PR: https://git.openjdk.java.net/jdk/pull/2852