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

rev 58769 : [mq]: type-descriptor-name

@@ -25,31 +25,39 @@
 package java.lang.invoke;
 
 import java.util.List;
 
 /**
- * An entity that has a field or method type descriptor
- *
- * @jvms 4.3.2 Field Descriptors
- * @jvms 4.3.3 Method Descriptors
+ * An entity that has a type descriptor.
  *
  * @since 12
  */
 public interface TypeDescriptor {
     /**
-     * Return the type descriptor string for this instance, which must be either
-     * a field type descriptor (JVMS 4.3.2) or method type descriptor (JVMS 4.3.3).
+     * Returns the descriptor string for this {@code TypeDescriptor} object.
+     *
+     * If this {@code TypeDescriptor} object can be described in nominal form,
+     * then this method returns a type descriptor as specified in JVMS {@jvms 4.3}.
+     * The result descriptor string can be used to produce
+     * a {@linkplain java.lang.constant.ConstantDesc nominal descriptor}.
+     *
+     * Otherwise, the result string is not a type descriptor.
+     * No {@linkplain java.lang.constant.ConstantDesc nominal descriptor}
+     * can be produced from the result string.
      *
-     * @return the type descriptor
+     * @return the descriptor string for this {@code TypeDescriptor} object
      * @jvms 4.3.2 Field Descriptors
      * @jvms 4.3.3 Method Descriptors
      */
     String descriptorString();
 
 
     /**
-     * An entity that has a field type descriptor
+     * An entity that has a field type descriptor.
+     * Field descriptors conforming to JVMS {@jvms 4.3.2} can be described
+     * nominally via {@link Class#describeConstable Class::describeConstable};
+     * otherwise they cannot be described nominally.
      *
      * @param <F> the class implementing {@linkplain TypeDescriptor.OfField}
      * @jvms 4.3.2 Field Descriptors
      * @since 12
      */

@@ -84,10 +92,13 @@
     }
 
 
     /**
      * An entity that has a method type descriptor
+     * Method descriptors conforming to JVMS {@jvms 4.3.3} can be described
+     * nominally via {@link MethodType#describeConstable MethodType::describeConstable};
+     * otherwise they cannot be described nominally.
      *
      * @param <F> the type representing field type descriptors
      * @param <M> the class implementing {@linkplain TypeDescriptor.OfMethod}
      * @jvms 4.3.2 Field Descriptors
      * @jvms 4.3.3 Method Descriptors