src/java.base/share/classes/java/lang/invoke/MethodType.java

@@ -97,10 +97,11 @@
  * <p>
  * When the JVM materializes a {@code MethodType} from a descriptor string,
  * all classes named in the descriptor must be accessible, and will be loaded.
  * (But the classes need not be initialized, as is the case with a {@code CONSTANT_Class}.)
  * This loading may occur at any time before the {@code MethodType} object is first derived.
+ *
  * @author John Rose, JSR 292 EG
  * @since 1.7
  */
 public final
 class MethodType

@@ -1137,21 +1138,24 @@
         Class<?>[] ptypes = listToArray(types);
         return makeImpl(rtype, ptypes, true);
     }
 
     /**
-     * Produces a bytecode descriptor representation of the method type.
+     * Returns a descriptor string for the 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.
      * <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 bytecode type descriptor representation
+     * @return the descriptor string for this method type
+     * @jvms 4.3.3 Method Descriptors
      */
     public String toMethodDescriptorString() {
         String desc = methodDescriptor;
         if (desc == null) {
             desc = BytecodeDescriptor.unparseMethod(this.rtype, this.ptypes);

@@ -1159,15 +1163,31 @@
         }
         return desc;
     }
 
     /**
-     * Return a field type descriptor string for this type
+     * Returns a descriptor string for this method type.
+     *
+     * <p> If none of the parameter types and return type is a {@linkplain Class#isHidden()
+     * hidden} class or interface, then the result is a method type descriptor string
+     * (JVMS {@jvms 4.3.3}). {@link MethodTypeDesc MethodTypeDesc} can be created from
+     * the result method type descriptor via
+     * {@link MethodTypeDesc#ofDescriptor(String) MethodTypeDesc::ofDescriptor}.
      *
-     * @return the descriptor string
-     * @jvms 4.3.2 Field Descriptors
+     * <p> If any of the parameter types and return type is a {@linkplain Class#isHidden()
+     * hidden} class or interface, then the result is a string of the form:
+     *    {@code "(<parameter-descriptors>)<return-descriptor>"}
+     * where {@code <parameter-descriptors>} is the concatenation of the
+     * {@linkplain Class#descriptorString() descriptor string} of all parameter types
+     * and the {@linkplain Class#descriptorString() descriptor string} of the return type.
+     * This method type cannot be described nominally and 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
      */
     @Override
     public String descriptorString() {
         return toMethodDescriptorString();
     }

@@ -1176,13 +1196,17 @@
     static String toFieldDescriptorString(Class<?> cls) {
         return BytecodeDescriptor.unparse(cls);
     }
 
     /**
-     * Return a nominal descriptor for this instance, if one can be
+     * Returns a nominal descriptor for this instance, if one can be
      * constructed, or an empty {@link Optional} if one cannot be.
      *
+     * <p> If any of the parameter types and return type is {@linkplain Class#isHidden()
+     * hidden}, then this method returns an empty {@link Optional} because
+     * this method type cannot be described in nominal form.
+     *
      * @return An {@link Optional} containing the resulting nominal descriptor,
      * or an empty {@link Optional} if one cannot be constructed.
      * @since 12
      */
     @Override