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

[Stuart Marks]

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.

src/java.base/share/classes/java/lang/reflect/Method.java line 597:

> 595:      * <p>Bridge methods may also be used by Java compiler in other
> 596:      * circumstances to span across difference in Java Language
> 597:      * semantics and JVM semantics.

If you decide to put less detail here, you could start with this statement. I think the main point is that there are some semantic gaps between methods in the Java language and in the JVM; bridge methods are necessary to "span" this gap. You might simply list some examples without explaining them fully.

Would this be "used by **a** Java compiler" or "used by **the** Java compiler?

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

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