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

[Joe Darcy]

Hi Stuart,

On 3/8/2021 6:02 PM, Stuart Marks wrote:
> On Sat, 6 Mar 2021 17:44:18 GMT, Joe Darcy <darcy at openjdk.org> wrote:
>
>>> The existing documentation of Method.isBridge isn't terribly helpful to the reader. This RFE proposes to given a common example of how bridge methods are used. The JLS does *not* have a section discussing bridge methods in detail; bridge methods are a compilation technique for lowering the Java language to the JVM, they are not a language feature per se. The example given is not exhaustive; there can be and are other uses of bridge methods.
>>>
>>> Once the text is agreed to; I'll update the copyright year as well.
>> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
>>
>>    Improve linkage for isSynethetic.
> src/java.base/share/classes/java/lang/reflect/Method.java line 593:
>
>> 591:      * result. (While the Java language specification forbids a class
>> 592:      * declaring two methods with the same parameter types but a
>> 593:      * different return type, the virtual machine does not.)
> I'm of two minds about this. This is certainly a good example of a bridge method. It doesn't motivate _why_ a bridge method is necessary in this case. It think it's because the language says you should be able to write code like
>      EnumSet<E> es2 = es.clone();
> so there needs to be a method defined in the class file whose return type is assignment-compatible  with `EnumSet`. However, a `clone` method that returns `Object` is the only one that can override the `Object::clone` method. Thus, a something is necessary to span this gap -- a bridge method.
>
> On the other hand, this might be too much detail for here. This is a really obscure location. It seems like somewhere else would be better, and where a full explanation with examples can be provided.


If someone is looking at isBridge and wondering what it does, having 
some discussion there some reasonable :-)

The text in question is not intended to be exhaustive and the exact use 
of bridge methods can, in principle, be Java compiler dependent.

Also, if in the future there are new JVM/platform facilities added so 
that bridge methods are not necessarily required for the cases where 
they are now used, I intended to write this text so it would still be 
correct.

Thanks,

-Joe