From 8c8e9d911d388f6ee621ed4d322efc56a9876708 Mon Sep 17 00:00:00 2001
From: Chen Liang <liach@openjdk.org>
Date: Fri, 30 Jun 2023 23:37:53 +0000
Subject: [PATCH] 8309819: Clarify API note in Class::getName and
 MethodType::toMethodDescriptorString

Reviewed-by: mchung
---
 .../share/classes/java/lang/Class.java        | 24 ++++-----
 .../classes/java/lang/invoke/MethodType.java  | 50 ++++++++++---------
 2 files changed, 37 insertions(+), 37 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/Class.java b/src/java.base/share/classes/java/lang/Class.java
index f0ef0b30461..a94e1aa9fde 100644
--- a/src/java.base/share/classes/java/lang/Class.java
+++ b/src/java.base/share/classes/java/lang/Class.java
@@ -170,7 +170,7 @@ import sun.reflect.misc.ReflectUtil;
  * may be hidden interfaces.
  *
  * The {@linkplain #getName() name of a hidden class or interface} is
- * not a <a href="ClassLoader.html#binary-name">binary name</a>,
+ * not a {@linkplain ClassLoader##binary-name binary name},
  * which means the following:
  * <ul>
  * <li>A hidden class or interface cannot be referenced by the constant pools
@@ -542,8 +542,8 @@ public final class Class<T> implements java.io.Serializable,
 
 
     /**
-     * Returns the {@code Class} with the given <a href="ClassLoader.html#binary-name">
-     * binary name</a> in the given module.
+     * Returns the {@code Class} with the given {@linkplain ClassLoader##binary-name
+     * binary name} in the given module.
      *
      * <p> This method attempts to locate and load the class or interface.
      * It does not link the class, and does not run the class initializer.
@@ -566,7 +566,7 @@ public final class Class<T> implements java.io.Serializable,
      * loads a class in another module.
      *
      * @param  module   A module
-     * @param  name     The <a href="ClassLoader.html#binary-name">binary name</a>
+     * @param  name     The {@linkplain ClassLoader##binary-name binary name}
      *                  of the class
      * @return {@code Class} object of the given name defined in the given module;
      *         {@code null} if not found.
@@ -894,11 +894,11 @@ public final class Class<T> implements java.io.Serializable,
      * not an array class, then:
      * <ul>
      * <li> If the class or interface is not {@linkplain #isHidden() hidden},
-     *      then the <a href="ClassLoader.html#binary-name">binary name</a>
+     *      then the {@linkplain ClassLoader##binary-name binary name}
      *      of the class or interface is returned.
      * <li> If the class or interface is hidden, then the result is a string
      *      of the form: {@code N + '/' + <suffix>}
-     *      where {@code N} is the <a href="ClassLoader.html#binary-name">binary name</a>
+     *      where {@code N} is the {@linkplain ClassLoader##binary-name binary name}
      *      indicated by the {@code class} file passed to
      *      {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
      *      Lookup::defineHiddenClass}, and {@code <suffix>} is an unqualified name.
@@ -918,7 +918,7 @@ public final class Class<T> implements java.io.Serializable,
      * <tr><th scope="row"> {@code boolean} <td style="text-align:center"> {@code Z}
      * <tr><th scope="row"> {@code byte}    <td style="text-align:center"> {@code B}
      * <tr><th scope="row"> {@code char}    <td style="text-align:center"> {@code C}
-     * <tr><th scope="row"> class or interface with <a href="ClassLoader.html#binary-name">binary name</a> <i>N</i>
+     * <tr><th scope="row"> class or interface with {@linkplain ClassLoader##binary-name binary name} <i>N</i>
      *                                      <td style="text-align:center"> {@code L}<em>N</em>{@code ;}
      * <tr><th scope="row"> {@code double}  <td style="text-align:center"> {@code D}
      * <tr><th scope="row"> {@code float}   <td style="text-align:center"> {@code F}
@@ -946,6 +946,9 @@ public final class Class<T> implements java.io.Serializable,
      *     returns "[[[[[[[I"
      * </pre></blockquote>
      *
+     * @apiNote
+     * Distinct class objects can have the same name but different class loaders.
+     *
      * @return  the name of the class, interface, or other entity
      *          represented by this {@code Class} object.
      * @jls 13.1 The Form of a Binary
@@ -4534,7 +4537,7 @@ public final class Class<T> implements java.io.Serializable,
      *      <blockquote>
      *      {@code "L" +} <em>N</em> {@code + "." + <suffix> + ";"}
      *      </blockquote>
-     *      where <em>N</em> is the <a href="ClassLoader.html#binary-name">binary name</a>
+     *      where <em>N</em> is the {@linkplain ClassLoader##binary-name binary name}
      *      encoded in internal form indicated by the {@code class} file passed to
      *      {@link MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
      *      Lookup::defineHiddenClass}, and {@code <suffix>} is an unqualified name.
@@ -4562,11 +4565,6 @@ public final class Class<T> implements java.io.Serializable,
      * is a one-letter code corresponding to a primitive type or {@code void}
      * ({@code "B", "C", "D", "F", "I", "J", "S", "Z", "V"}) (JVMS {@jvms 4.3.2}).
      *
-     * @apiNote
-     * This is not a strict inverse of {@link #forName};
-     * distinct classes which share a common name but have different class loaders
-     * will have identical descriptor strings.
-     *
      * @return the descriptor string for this {@code Class} object
      * @jvms 4.3.2 Field Descriptors
      * @since 12
diff --git a/src/java.base/share/classes/java/lang/invoke/MethodType.java b/src/java.base/share/classes/java/lang/invoke/MethodType.java
index 76f00d3d213..31f7ab862f5 100644
--- a/src/java.base/share/classes/java/lang/invoke/MethodType.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java
@@ -51,7 +51,6 @@ import sun.security.util.SecurityConstants;
 
 import static java.lang.invoke.MethodHandleStatics.UNSAFE;
 import static java.lang.invoke.MethodHandleStatics.newIllegalArgumentException;
-import static java.lang.invoke.MethodType.fromDescriptor;
 
 /**
  * A method type represents the arguments and return type accepted and
@@ -1159,26 +1158,29 @@ class MethodType
     }
 
     /**
-     * Finds or creates an instance of a method type, given the spelling of its bytecode descriptor.
-     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
+     * Finds or creates an instance of a method type of the given method descriptor
+     * (JVMS {@jvms 4.3.3}). This method is a convenience method for
+     * {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * Any class or interface name embedded in the descriptor string will be
-     * resolved by the given loader (or if it is null, on the system class loader).
-     * <p>
-     * Note that it is possible to encounter method types which cannot be
-     * constructed by this method, because their component types are
-     * not all reachable from a common class loader.
+     * resolved by the given loader (or if it is {@code null}, on the system class loader).
+     *
+     * @apiNote
+     * It is possible to encounter method types that have valid descriptors but
+     * cannot be constructed by this method, because their component types are
+     * not visible from a common class loader.
      * <p>
      * This method is included for the benefit of applications that must
      * generate bytecodes that process method handles and {@code invokedynamic}.
-     * @param descriptor a bytecode-level type descriptor string "(T...)T"
+     * @param descriptor a method descriptor string
      * @param loader the class loader in which to look up the types
-     * @return a method type matching the bytecode-level type descriptor
-     * @throws NullPointerException if the string is null
-     * @throws IllegalArgumentException if the string is not well-formed
+     * @return a method type of the given method descriptor
+     * @throws NullPointerException if the string is {@code null}
+     * @throws IllegalArgumentException if the string is not a method descriptor
      * @throws TypeNotPresentException if a named type cannot be found
      * @throws SecurityException if the security manager is present and
      *         {@code loader} is {@code null} and the caller does not have the
      *         {@link RuntimePermission}{@code ("getClassLoader")}
+     * @jvms 4.3.3 Method Descriptors
      */
     public static MethodType fromMethodDescriptorString(String descriptor, ClassLoader loader)
         throws IllegalArgumentException, TypeNotPresentException
@@ -1218,19 +1220,20 @@ class MethodType
     }
 
     /**
-     * Returns a descriptor string for the method type.  This method
+     * {@return the descriptor string for this method type} This method
      * is equivalent to calling {@link #descriptorString() MethodType::descriptorString}.
      *
-     * <p>
-     * Note that this is not a strict inverse of {@link #fromMethodDescriptorString fromMethodDescriptorString}.
-     * Two distinct classes which share a common name but have different class loaders
-     * will appear identical when viewed within descriptor strings.
+     * @apiNote
+     * This is not a strict inverse of {@link #fromMethodDescriptorString
+     * fromMethodDescriptorString} which requires a method type descriptor
+     * (JVMS {@jvms 4.3.3}) and a suitable class loader argument.
+     * Two distinct {@code MethodType} objects can have an identical
+     * descriptor string as distinct classes can have the same name
+     * but different class loaders.
+     *
      * <p>
      * This method is included for the benefit of applications that must
      * generate bytecodes that process method handles and {@code invokedynamic}.
-     * {@link #fromMethodDescriptorString(java.lang.String, java.lang.ClassLoader) fromMethodDescriptorString},
-     * because the latter requires a suitable class loader argument.
-     * @return the descriptor string for this method type
      * @jvms 4.3.3 Method Descriptors
      * @see <a href="#descriptor">Nominal Descriptor for {@code MethodType}</a>
      */
@@ -1244,16 +1247,16 @@ class MethodType
     }
 
     /**
-     * Returns a descriptor string for this method type.
+     * {@return the descriptor string for this method type}
      *
      * <p>
-     * If this method type can be <a href="#descriptor">described nominally</a>,
+     * If this method type can be {@linkplain ##descriptor described nominally},
      * then the result is a method type descriptor (JVMS {@jvms 4.3.3}).
      * {@link MethodTypeDesc MethodTypeDesc} for this method type
      * can be produced by calling {@link MethodTypeDesc#ofDescriptor(String)
      * MethodTypeDesc::ofDescriptor} with the result descriptor string.
      * <p>
-     * If this method type cannot be <a href="#descriptor">described nominally</a>
+     * If this method type cannot be {@linkplain ##descriptor described nominally}
      * and the result is a string of the form:
      * <blockquote>{@code "(<parameter-descriptors>)<return-descriptor>"}</blockquote>
      * where {@code <parameter-descriptors>} is the concatenation of the
@@ -1262,7 +1265,6 @@ class MethodType
      * of the return type. No {@link java.lang.constant.MethodTypeDesc MethodTypeDesc}
      * can be produced from the result string.
      *
-     * @return the descriptor string for this method type
      * @since 12
      * @jvms 4.3.3 Method Descriptors
      * @see <a href="#descriptor">Nominal Descriptor for {@code MethodType}</a>