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

@@ -25,23 +25,32 @@
 package java.lang.invoke;
 
 import java.util.List;
 
 /**
- * An entity that has a field or method type descriptor
+ * An entity that has a type descriptor.
  *
  * @jvms 4.3.2 Field Descriptors
  * @jvms 4.3.3 Method Descriptors
  *
  * @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).
+     * Return the descriptor string for this {@code TypeDescriptor} object.
      *
-     * @return the type descriptor
+     * If this {@code TypeDescriptor} object can be described nominally, then
+     * this method returns a field type descriptor (JVMS {@jvms 4.3.2}) or
+     * method type descriptor (JVMS {@jvms 4.3.3}).  The result descriptor
+     * can be used to produce a {@linkplain java.lang.constant.ConstantDesc
+     * nominal descriptor}.
+     *
+     * Otherwise, the result string is not a valid type descriptor and
+     * no {@linkplain java.lang.constant.ConstantDesc nominal descriptor}
+     * can be produced from the result string.
+     *
+     * @return the descriptor string for this {@code TypeDescriptor} object
      * @jvms 4.3.2 Field Descriptors
      * @jvms 4.3.3 Method Descriptors
      */
     String descriptorString();