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

*** 97,106 ****
--- 97,107 ----
   * <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,1157 ****
          Class<?>[] ptypes = listToArray(types);
          return makeImpl(rtype, ptypes, true);
      }
  
      /**
!      * Produces a bytecode descriptor representation of the method type.
       * <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
       */
      public String toMethodDescriptorString() {
          String desc = methodDescriptor;
          if (desc == null) {
              desc = BytecodeDescriptor.unparseMethod(this.rtype, this.ptypes);
--- 1138,1161 ----
          Class<?>[] ptypes = listToArray(types);
          return makeImpl(rtype, ptypes, true);
      }
  
      /**
!      * 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 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,1173 ****
          }
          return desc;
      }
  
      /**
!      * Return a field type descriptor string for this type
       *
!      * @return the descriptor string
!      * @jvms 4.3.2 Field Descriptors
       * @since 12
       */
      @Override
      public String descriptorString() {
          return toMethodDescriptorString();
      }
--- 1163,1193 ----
          }
          return desc;
      }
  
      /**
!      * 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}.
       *
!      * <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,1188 ****
      static String toFieldDescriptorString(Class<?> cls) {
          return BytecodeDescriptor.unparse(cls);
      }
  
      /**
!      * Return a nominal descriptor for this instance, if one can be
       * constructed, or an empty {@link Optional} if one cannot be.
       *
       * @return An {@link Optional} containing the resulting nominal descriptor,
       * or an empty {@link Optional} if one cannot be constructed.
       * @since 12
       */
      @Override
--- 1196,1212 ----
      static String toFieldDescriptorString(Class<?> cls) {
          return BytecodeDescriptor.unparse(cls);
      }
  
      /**
!      * 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