--- old/src/java.base/share/classes/java/lang/invoke/MethodType.java 2020-04-08 14:54:27.000000000 -0700 +++ new/src/java.base/share/classes/java/lang/invoke/MethodType.java 2020-04-08 14:54:27.000000000 -0700 @@ -99,6 +99,7 @@ * 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 */ @@ -1139,7 +1140,9 @@ } /** - * 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}. + * *
* 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 @@ -1149,7 +1152,8 @@ * 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; @@ -1161,11 +1165,27 @@ } /** - * Return a field type descriptor string for this type + * Returns a descriptor string for this method type. + * + *
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 + *
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 "( 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