From 67ea3bd6a471ecef088cdde6242ae243b88974e5 Mon Sep 17 00:00:00 2001
From: Joe Darcy <darcy@openjdk.org>
Date: Wed, 10 Mar 2021 03:43:53 +0000
Subject: [PATCH] 8263102: Expand documention of Method.isBridge

Reviewed-by: smarks
---
 .../java/lang/reflect/Constructor.java        |  3 +-
 .../classes/java/lang/reflect/Executable.java |  3 +-
 .../classes/java/lang/reflect/Method.java     | 43 ++++++++++++++++---
 3 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/reflect/Constructor.java b/src/java.base/share/classes/java/lang/reflect/Constructor.java
index a3070717f4828..ca01b7f423da3 100644
--- a/src/java.base/share/classes/java/lang/reflect/Constructor.java
+++ b/src/java.base/share/classes/java/lang/reflect/Constructor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -511,6 +511,7 @@ public boolean isVarArgs() {
     /**
      * {@inheritDoc}
      * @jls 13.1 The Form of a Binary
+     * @jvms 4.6 Methods
      * @since 1.5
      */
     @Override
diff --git a/src/java.base/share/classes/java/lang/reflect/Executable.java b/src/java.base/share/classes/java/lang/reflect/Executable.java
index 9375aa18fe734..c7daae19653e1 100644
--- a/src/java.base/share/classes/java/lang/reflect/Executable.java
+++ b/src/java.base/share/classes/java/lang/reflect/Executable.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -518,6 +518,7 @@ public boolean isVarArgs()  {
      * construct as defined by
      * <cite>The Java Language Specification</cite>.
      * @jls 13.1 The Form of a Binary
+     * @jvms 4.6 Methods
      */
     public boolean isSynthetic() {
         return Modifier.isSynthetic(getModifiers());
diff --git a/src/java.base/share/classes/java/lang/reflect/Method.java b/src/java.base/share/classes/java/lang/reflect/Method.java
index 4e28846dc5d8e..f163964724cea 100644
--- a/src/java.base/share/classes/java/lang/reflect/Method.java
+++ b/src/java.base/share/classes/java/lang/reflect/Method.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -567,12 +567,44 @@ public Object invoke(Object obj, Object... args)
     }
 
     /**
-     * Returns {@code true} if this method is a bridge
-     * method; returns {@code false} otherwise.
+     * {@return {@code true} if this method is a bridge
+     * method; returns {@code false} otherwise}
      *
-     * @return true if and only if this method is a bridge
-     * method as defined by the Java Language Specification.
+     * @apiNote
+     * A bridge method is a {@linkplain isSynthetic 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.
+     *
+     * <p>One example use of bridge methods is as a technique for a
+     * Java compiler to support <i>covariant overrides</i>, 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 {@link
+     * java.lang.Cloneable Cloneable} class where the {@link
+     * Object#clone() clone} method inherited from {@code
+     * java.lang.Object} is overridden and declared to return the type
+     * of the class. For example, {@code Object} declares
+     * <pre>{@code protected Object clone() throws CloneNotSupportedException {...}}</pre>
+     * and {@code EnumSet<E>} declares its language-level {@linkplain
+     * java.util.EnumSet#clone() covariant override}
+     * <pre>{@code public EnumSet<E> clone() {...}}</pre>
+     * If this technique was being used, the resulting class file for
+     * {@code EnumSet} would have two {@code clone} methods, one
+     * returning {@code EnumSet<E>} and the second a bridge method
+     * returning {@code Object}. The bridge method is a JVM-level
+     * override of {@code Object.clone()}.  The body of the {@code
+     * clone} bridge method calls its non-bridge counterpart and
+     * returns its result.
      * @since 1.5
+     *
+     * @jls 8.4.8.3 Requirements in Overriding and Hiding
+     * @jls 15.12.4.5 Create Frame, Synchronize, Transfer Control
+     * @jvms 4.6 Methods
      */
     public boolean isBridge() {
         return (getModifiers() & Modifier.BRIDGE) != 0;
@@ -590,6 +622,7 @@ public boolean isVarArgs() {
     /**
      * {@inheritDoc}
      * @jls 13.1 The Form of a Binary
+     * @jvms 4.6 Methods
      * @since 1.5
      */
     @Override