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

[Joe Darcy]

On 3/9/2021 12:03 PM, Stuart Marks wrote:
> 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.

Pushed a refinement along those lines; new text:

A bridge method is a synthetic method created by a Java compiler 
alongside a method originating from the source code. Bridge methods are 
used by Java compilers in various circumstances to span differences in 
Java programming language semantics and JVM semantics. One example use 
of bridge methods is as technique for a Java compiler to support 
covariant overrides, where a subclass overrides a method and gives the 
new method a more specific return type than the method in the 
superclass. While the Java language specification forbids a class 
declaring two methods with the same parameter types but a different 
return type, the virtual machine does not. A common case where covariant 
overrides are used is for a Cloneable class where the clone method 
inherited from java.lang.Object is overridden and declared to return the 
type of the class. For example, Object declares
protected Object clone() throws CloneNotSupportedException {...}
and EnumSet<E> declares its language-level covariant override
public EnumSet<E> clone() {...}
If this technique was being used, the resulting class file for EnumSet 
would have two clone methods, one returning EnumSet<E> and the second a 
bridge method returning Object. The bridge method is a JVM-level 
override of Object.clone(). The body of the clone bridge method calls 
its non-bridge counterpart and returns its result.

-Joe