changeset 50336:0d1b8810b899 condy-folding

More specification tweaks and cleanups for java.lang.invoke.constant
author briangoetz
date Thu, 19 Apr 2018 17:38:29 -0400
parents 3c5bb1c5919c
children be1ff3649a9c
files src/java.base/share/classes/java/lang/Enum.java src/java.base/share/classes/java/lang/invoke/constant/AsTypeMethodHandleDesc.java src/java.base/share/classes/java/lang/invoke/constant/ClassDesc.java src/java.base/share/classes/java/lang/invoke/constant/Constable.java src/java.base/share/classes/java/lang/invoke/constant/ConstantClassDesc.java src/java.base/share/classes/java/lang/invoke/constant/ConstantDesc.java src/java.base/share/classes/java/lang/invoke/constant/ConstantDescs.java src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodHandleDesc.java src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodTypeDesc.java src/java.base/share/classes/java/lang/invoke/constant/DescBootstraps.java src/java.base/share/classes/java/lang/invoke/constant/DynamicCallSiteDesc.java src/java.base/share/classes/java/lang/invoke/constant/DynamicConstantDesc.java src/java.base/share/classes/java/lang/invoke/constant/EnumDesc.java src/java.base/share/classes/java/lang/invoke/constant/MethodHandleDesc.java src/java.base/share/classes/java/lang/invoke/constant/MethodTypeDesc.java src/java.base/share/classes/java/lang/invoke/constant/PrimitiveClassDesc.java src/java.base/share/classes/java/lang/invoke/constant/VarHandleDesc.java src/java.base/share/classes/java/lang/invoke/constant/package-info.java
diffstat 18 files changed, 524 insertions(+), 498 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/Enum.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/Enum.java	Thu Apr 19 17:38:29 2018 -0400
@@ -207,7 +207,7 @@
     }
 
     @Override
-    public Optional<EnumDesc<E>> describeConstable(MethodHandles.Lookup lookup) {
+    public final Optional<EnumDesc<E>> describeConstable(MethodHandles.Lookup lookup) {
         return getDeclaringClass()
                 .describeConstable(lookup)
                 .map(c -> EnumDesc.of(c, name));
--- a/src/java.base/share/classes/java/lang/invoke/constant/AsTypeMethodHandleDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/AsTypeMethodHandleDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -36,9 +36,9 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * A nominal descriptor for a {@link MethodHandle} constant that performs
- * a {@link MethodHandle#asType(MethodType)} adaptation on another
- * {@link MethodHandle}.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * {@link MethodHandle} constant that performs a {@link MethodHandle#asType(MethodType)}
+ * adaptation on another {@link MethodHandle}.
  */
 final class AsTypeMethodHandleDesc extends DynamicConstantDesc<MethodHandle>
         implements MethodHandleDesc {
--- a/src/java.base/share/classes/java/lang/invoke/constant/ClassDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ClassDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -38,7 +38,8 @@
 import static java.util.stream.Collectors.joining;
 
 /**
- * A nominal descriptor for a {@link Class} constant.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * {@link Class} constant.
  *
  * <p>For common system types, including all the primitive types, there are
  * predefined {@linkplain ClassDesc} constants in {@link ConstantDescs}.  To create
@@ -46,19 +47,21 @@
  * {@link #ofDescriptor(String)}; to create a {@linkplain ClassDesc} for an array
  * type, use {@link #ofDescriptor(String)}, or first obtain a
  * {@linkplain ClassDesc} for the component type and then call the {@link #array()}
- * method.
+ * or {@link #array(int)} methods.
  *
  * @see ConstantDescs
  */
 public interface ClassDesc
         extends ConstantDesc<Class<?>>, Constable<ConstantDesc<Class<?>>> {
+
     /**
-     * Create a {@linkplain ClassDesc} from a class name.
+     * Create a {@linkplain ClassDesc} given a class name.
      *
      * @param name the fully qualified (dot-separated) binary class name
      * @return a {@linkplain ClassDesc} describing the desired class
-     * @throws IllegalArgumentException if the name string does not
-     * describe a valid class name
+     * @throws NullPointerException if any argument is {@code null}
+     * @throws IllegalArgumentException if the name string is not in the
+     * correct format
      */
     @Foldable
     static ClassDesc of(String name) {
@@ -67,12 +70,13 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} from a package name and an unqualified
+     * Create a {@linkplain ClassDesc} given a package name and an unqualified
      * class name.
      *
      * @param packageName the package name (dot-separated)
      * @param className the unqualified class name
      * @return a {@linkplain ClassDesc} describing the desired class
+     * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalArgumentException if the package name or class name are
      * not in the correct format
      */
@@ -87,13 +91,13 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} from a descriptor string for a class
+     * Create a {@linkplain ClassDesc} given a descriptor string.
      *
      * @param descriptor a field descriptor string, as per JVMS 4.3.2
      * @return a {@linkplain ClassDesc} describing the desired class
-     * @throws NullPointerException if the descriptor string is null
-     * @throws IllegalArgumentException if the descriptor string is not
-     * a valid class descriptor
+     * @throws NullPointerException if any argument is {@code null}
+     * @throws IllegalArgumentException if the name string is not in the
+     * correct format
      */
     @Foldable
     static ClassDesc ofDescriptor(String descriptor) {
@@ -104,19 +108,19 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} describing an array of the type
-     * described by this {@linkplain ClassDesc}
+     * Create a {@linkplain ClassDesc} for an array type whose component type
+     * is described by this {@linkplain ClassDesc}.
      *
      * @return a {@linkplain ClassDesc} describing the array type
      */
     @Foldable
     default ClassDesc array() {
-        return ClassDesc.ofDescriptor("[" + descriptorString());
+        return array(1);
     }
 
     /**
-     * Create a {@linkplain ClassDesc} describing an array of the type
-     * described by this {@linkplain ClassDesc}, of the specified rank
+     * Create a {@linkplain ClassDesc} for an array type of the specified rank,
+     * whose component type is described by this {@linkplain ClassDesc}.
      *
      * @param rank the rank of the array
      * @return a {@linkplain ClassDesc} describing the array type
@@ -126,17 +130,16 @@
     default ClassDesc array(int rank) {
         if (rank <= 0)
             throw new IllegalArgumentException();
-        ClassDesc cr = this;
-        for (int i=0; i<rank; i++)
-            cr = cr.array();
-        return cr;
+        return ClassDesc.ofDescriptor("[".repeat(rank) + descriptorString());
     }
 
     /**
-     * Create a {@linkplain ClassDesc} describing an inner class of the
-     * class or interface type described by this {@linkplain ClassDesc}
+     * Create a {@linkplain ClassDesc} for an inner class of the class or
+     * interface type described by this {@linkplain ClassDesc}.
+     *
      * @param innerName the unqualified name of the inner class
      * @return a {@linkplain ClassDesc} describing the inner class
+     * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalStateException if this {@linkplain ClassDesc} does not
      * describe a class or interface type
      */
@@ -149,12 +152,14 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} describing a multiply nested inner class of the
-     * class or interface type described by this {@linkplain ClassDesc}
+     * Create a {@linkplain ClassDesc} for an inner class of the class or
+     * interface type described by this {@linkplain ClassDesc}.
      *
-     * @param firstInnerName the name of the first level of inner class
-     * @param moreInnerNames the name(s) of the remaining levels of inner class
+     * @param firstInnerName the unqualified name of the first level of inner class
+     * @param moreInnerNames the unqualified name(s) of the remaining levels of
+     *                       inner class
      * @return a {@linkplain ClassDesc} describing the inner class
+     * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalStateException if this {@linkplain ClassDesc} does not
      * describe a class or interface type
      */
@@ -168,7 +173,7 @@
     }
 
     /**
-     * Returns whether this {@linkplain ClassDesc} describes an array type
+     * Returns whether this {@linkplain ClassDesc} describes an array type.
      *
      * @return whether this {@linkplain ClassDesc} describes an array type
      */
@@ -177,7 +182,7 @@
     }
 
     /**
-     * Returns whether this {@linkplain ClassDesc} describes a primitive type
+     * Returns whether this {@linkplain ClassDesc} describes a primitive type.
      *
      * @return whether this {@linkplain ClassDesc} describes a primitive type
      */
@@ -186,7 +191,7 @@
     }
 
     /**
-     * Returns whether this {@linkplain ClassDesc} describes a class or interface type
+     * Returns whether this {@linkplain ClassDesc} describes a class or interface type.
      *
      * @return whether this {@linkplain ClassDesc} describes a class or interface type
      */
@@ -196,7 +201,7 @@
 
     /**
      * Returns the component type of this {@linkplain ClassDesc}, if it describes
-     * an array type
+     * an array type.
      *
      * @return a {@linkplain ClassDesc} describing the component type
      * @throws IllegalStateException if this {@linkplain ClassDesc} does not
@@ -211,7 +216,7 @@
 
     /**
      * Returns the package name of this {@linkplain ClassDesc}, if it describes
-     * a class or interface type
+     * a class or interface type.
      *
      * @return the package name, or the empty string if no package
      * @throws IllegalStateException if this {@linkplain ClassDesc} does not
@@ -226,9 +231,9 @@
     }
 
     /**
-     * Returns a human-readable name for the type described by this descriptor
+     * Returns a human-readable name for the type described by this descriptor.
      *
-     * @return a human-readable name for the type described by this descriptor
+     * @return the human-readable name
      */
     default String displayName() {
         if (descriptorString().length() == 1)
@@ -242,20 +247,16 @@
             ClassDesc c = this;
             for (int i=0; i<depth; i++)
                 c = c.componentType();
-            String name = c.displayName();
-            StringBuilder sb = new StringBuilder(name.length() + 2*depth);
-            sb.append(name);
-            for (int i=0; i<depth; i++)
-                sb.append("[]");
-            return sb.toString();
+            return c.displayName() + "[]".repeat(depth);
         }
         else
             throw new IllegalStateException(descriptorString());
     }
 
     /**
-     * Return the type descriptor string
-     * @return the type descriptor string
+     * Return the descriptor string for this type, as per JVMS 4.3.2
+     *
+     * @return the descriptor string
      */
     @Foldable
     String descriptorString();
--- a/src/java.base/share/classes/java/lang/invoke/constant/Constable.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/Constable.java	Thu Apr 19 17:38:29 2018 -0400
@@ -68,7 +68,7 @@
      * constructed.
      *
      * @implSpec This method behaves as if {@link #describeConstable(MethodHandles.Lookup)}
-     * were called with a lookup parameter of {@code MethodHandles.publicLookup()}.
+     * were called with a lookup parameter of {@link MethodHandles#publicLookup()}.
      *
      * @return An {@link Optional} containing the resulting nominal descriptor,
      * or an empty {@link Optional} if one cannot be constructed
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantClassDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantClassDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -30,17 +30,24 @@
 import java.util.Optional;
 import java.util.regex.Pattern;
 
+import jdk.internal.lang.annotation.Foldable;
+
 import static java.lang.invoke.constant.ConstantDescs.CR_ClassDesc;
+import static java.lang.invoke.constant.ConstantDescs.CR_String;
 import static java.lang.invoke.constant.ConstantUtils.dropFirstAndLastChar;
 import static java.lang.invoke.constant.ConstantUtils.internalToBinary;
 import static java.util.Objects.requireNonNull;
 
 /**
- * A nominal descriptor for a class, interface, or array type.  A
- * {@linkplain ConstantClassDesc} corresponds to a {@code Constant_Class_info}
- * entry in the constant pool of a classfile.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a class,
+ * interface, or array type.  A {@linkplain ConstantClassDesc} corresponds to a
+ * {@code Constant_Class_info} entry in the constant pool of a classfile.
  */
 public class ConstantClassDesc implements ClassDesc {
+    @Foldable
+    private static final ConstantMethodHandleDesc BSM_CLASSDESC
+            = ConstantDescs.ofConstantBootstrap(ClassDesc.of("java.lang.invoke.constant", "ConstantClassDesc"),
+                                                "constantBootstrap", CR_ClassDesc, CR_String);
     private static final Pattern TYPE_DESC = Pattern.compile("(\\[*)(V|I|J|S|B|C|F|D|Z|L[^/.\\[;][^.\\[;]*;)");
 
     private final String descriptor;
@@ -92,7 +99,22 @@
 
     @Override
     public Optional<? extends ConstantDesc<? super ConstantDesc<Class<?>>>> describeConstable(MethodHandles.Lookup lookup) {
-        return Optional.of(DynamicConstantDesc.of(DescBootstraps.BSM_CLASSDESC, CR_ClassDesc).withArgs(descriptor));
+        return Optional.of(DynamicConstantDesc.of(BSM_CLASSDESC, CR_ClassDesc).withArgs(descriptor));
+    }
+
+    /**
+     * Constant bootstrap method for representing a {@linkplain ClassDesc} in
+     * the constant pool of a classfile.
+     *
+     * @param lookup ignored
+     * @param name ignored
+     * @param clazz ignored
+     * @param descriptor a field descriptor string for the class, as per JVMS 4.3.2
+     * @return the {@linkplain ClassDesc}
+     */
+    public static ClassDesc constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
+                                              String descriptor) {
+        return ClassDesc.ofDescriptor(descriptor);
     }
 
     @Override
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -30,9 +30,10 @@
 import java.lang.invoke.MethodType;
 
 /**
- * A nominal descriptor for a loadable constant value, as defined in JVMS 4.4.
- * Such a descriptor can be resolved via {@link ConstantDesc#resolveConstantDesc(MethodHandles.Lookup)}
- * to yield the constant value itself.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a loadable
+ * constant value, as defined in JVMS 4.4. Such a descriptor can be resolved via
+ * {@link ConstantDesc#resolveConstantDesc(MethodHandles.Lookup)} to yield the
+ * constant value itself.
  *
  * <p>Class names in a nominal descriptor, like class names in the constant pool
  * of a classfile, must be interpreted with respect to a particular to a class
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantDescs.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantDescs.java	Thu Apr 19 17:38:29 2018 -0400
@@ -41,9 +41,10 @@
 import static java.lang.invoke.constant.MethodHandleDesc.Kind.STATIC;
 
 /**
- * Predefined values of nominal descriptors for common constants, including
- * descriptors for primitive class types and other common platform types,
- * and descriptors for method handles for standard bootstrap methods.
+ * Predefined values of <a href="package-summary.html#nominal">nominal descriptor</a>
+ * for common constants, including descriptors for primitive class types and
+ * other common platform types, and descriptors for method handles for standard
+ * bootstrap methods.
  *
  * @see ConstantDesc
  */
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodHandleDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodHandleDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -34,17 +34,23 @@
 import jdk.internal.lang.annotation.Foldable;
 
 import static java.lang.invoke.constant.ConstantDescs.CR_MethodHandleDesc;
+import static java.lang.invoke.constant.ConstantDescs.CR_String;
 import static java.lang.invoke.constant.ConstantUtils.validateClassOrInterface;
 import static java.lang.invoke.constant.ConstantUtils.validateMemberName;
 import static java.lang.invoke.constant.MethodHandleDesc.Kind.CONSTRUCTOR;
 import static java.util.Objects.requireNonNull;
 
 /**
- * A nominal descriptor for a direct {@link MethodHandle}.  A
- * {@linkplain ConstantMethodHandleDesc} corresponds to a {@code Constant_MethodHandle_info}
- * entry in the constant pool of a classfile.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a direct
+ * {@link MethodHandle}.  A {@linkplain ConstantMethodHandleDesc} corresponds to
+ * a {@code Constant_MethodHandle_info} entry in the constant pool of a classfile.
  */
 public class ConstantMethodHandleDesc implements MethodHandleDesc {
+    @Foldable
+    private static final ConstantMethodHandleDesc BSM_METHODHANDLEDESC
+            = ConstantDescs.ofConstantBootstrap(ClassDesc.of("java.lang.invoke.constant", "ConstantMethodHandleDesc"),
+                                                "constantBootstrap", CR_MethodHandleDesc,
+                                                CR_String, CR_String, CR_String, CR_String);
 
     private final Kind kind;
     private final ClassDesc owner;
@@ -54,6 +60,7 @@
     /**
      * Construct a {@linkplain ConstantMethodHandleDesc} for a method or field
      * from a kind, owner, name, and type
+     *
      * @param kind the kind of the method handle
      * @param owner the declaring class or interface for the method
      * @param name the name of the method (ignored if {@code kind} is
@@ -109,7 +116,8 @@
 
     /**
      * Return the {@code kind} of the method handle described by this nominal
-     * descriptor
+     * descriptor.
+     *
      * @return the {@link Kind}
      */
     @Foldable
@@ -117,17 +125,18 @@
 
     /**
      * Return the {@code refKind} of the method handle described by this nominal
-     * reference, as defined by {@link MethodHandleInfo}
+     * reference, as defined by {@link MethodHandleInfo}.
+     *
      * @return the reference kind
      */
     @Foldable
     public int refKind() { return kind.refKind; }
 
     /**
-     * Return the class which declares the method or field described by
-     * this nominal descriptor
+     * Return a {@link ClassDesc} describing the class declaring the
+     * method or field described by this nominal descriptor.
      *
-     * @return the class in which the method or field is declared
+     * @return the class declaring the method or field
      */
     @Foldable
     public ClassDesc owner() {
@@ -135,9 +144,9 @@
     }
 
     /**
-     * Return the name of the method or field described by this nominal descriptor
+     * Return the name of the method or field described by this nominal descriptor.
      *
-     * @return the name of the method
+     * @return the name of the method or field
      */
     @Foldable
     public String methodName() {
@@ -145,7 +154,9 @@
     }
 
     /**
-     * Return the type of the method described by this nominal descriptor
+     * Return a {@link MethodTypeDesc} describing the invocation type of the
+     * method handle described by this nominal descriptor
+     *
      * @return the method type
      */
     @Foldable
@@ -182,10 +193,32 @@
 
     @Override
     public Optional<? extends ConstantDesc<? super ConstantDesc<MethodHandle>>> describeConstable(MethodHandles.Lookup lookup) {
-        return Optional.of(DynamicConstantDesc.of(DescBootstraps.BSM_METHODHANDLEDESC, CR_MethodHandleDesc)
+        return Optional.of(DynamicConstantDesc.of(BSM_METHODHANDLEDESC, CR_MethodHandleDesc)
                                               .withArgs(kind.toString(), owner.descriptorString(), name, type.descriptorString()));
     }
 
+    /**
+     * Constant bootstrap method for representing a {@linkplain MethodHandleDesc} in
+     * the constant pool of a classfile.
+     *
+     * @param lookup ignored
+     * @param name ignored
+     * @param clazz ignored
+     * @param bsmKindName The name of an {@code enum} constant from {@link Kind}
+     * @param memberOwner A field type descriptor for the class declaring the
+     *                 method, field, or constructor, as per JVMS 4.3.2
+     * @param memberName The name of the method or field, as per JVMS 4.2.2
+     * @param memberType A method type descriptor for the method handle being
+     *                described, as per JVMS 4.3.3
+     * @return the {@linkplain MethodHandleDesc}
+     */
+    public static MethodHandleDesc constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
+                                                     String bsmKindName, String memberOwner, String memberName, String memberType) {
+        return MethodHandleDesc.of(MethodHandleDesc.Kind.valueOf(bsmKindName),
+                                   ClassDesc.ofDescriptor(memberOwner), name,
+                                   MethodTypeDesc.ofDescriptor(memberType));
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodTypeDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodTypeDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -36,14 +36,19 @@
 import java.util.regex.Pattern;
 
 import static java.lang.invoke.constant.ConstantDescs.CR_MethodTypeDesc;
+import static java.lang.invoke.constant.ConstantDescs.CR_String;
 import static java.util.Objects.requireNonNull;
 
 /**
- * A nominal descriptor for a {@link MethodType}.  A {@linkplain ConstantMethodTypeDesc}
- * corresponds to a {@code Constant_MethodType_info} entry in the constant pool
- * of a classfile.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * {@link MethodType}.  A {@linkplain ConstantMethodTypeDesc} corresponds to a
+ * {@code Constant_MethodType_info} entry in the constant pool of a classfile.
  */
 public final class ConstantMethodTypeDesc implements MethodTypeDesc {
+    @Foldable
+    private static final ConstantMethodHandleDesc BSM_METHODTYPEDESC
+            = ConstantDescs.ofConstantBootstrap(ClassDesc.of("java.lang.invoke.constant", "ConstantMethodTypeDesc"),
+                                                "constantBootstrap", CR_MethodTypeDesc, CR_String);
 
     private static final Pattern TYPE_DESC = Pattern.compile("(\\[*)(V|I|J|S|B|C|F|D|Z|L[^/.\\[;][^.\\[;]*;)");
     private static final Pattern pattern = Pattern.compile("\\((.*)\\)(.*)");
@@ -68,7 +73,7 @@
     }
 
     /**
-     * Create a {@linkplain ConstantMethodTypeDesc} from a method descriptor string
+     * Create a {@linkplain ConstantMethodTypeDesc} given a method descriptor string.
      *
      * @param descriptor the method descriptor string, as per JVMS 4.3.3
      * @return a {@linkplain ConstantMethodTypeDesc} describing the desired method type
@@ -76,7 +81,7 @@
      * method descriptor
      */
     @Foldable
-    static MethodTypeDesc ofDescriptor(String descriptor) {
+    static ConstantMethodTypeDesc ofDescriptor(String descriptor) {
         // @@@ Replace validation with a lower-overhead mechanism than regex
         // Follow the trail from MethodType.fromMethodDescriptorString to
         // parsing code in sun/invoke/util/BytecodeDescriptor.java which could
@@ -177,7 +182,22 @@
 
     @Override
     public Optional<? extends ConstantDesc<? super ConstantDesc<MethodType>>> describeConstable(MethodHandles.Lookup lookup) {
-        return Optional.of(DynamicConstantDesc.of(DescBootstraps.BSM_METHODTYPEDESC, CR_MethodTypeDesc).withArgs(descriptorString()));
+        return Optional.of(DynamicConstantDesc.of(BSM_METHODTYPEDESC, CR_MethodTypeDesc).withArgs(descriptorString()));
+    }
+
+    /**
+     * Constant bootstrap method for representing a {@linkplain MethodTypeDesc} in
+     * the constant pool of a classfile.
+     *
+     * @param lookup ignored
+     * @param name ignored
+     * @param clazz ignored
+     * @param descriptor a method descriptor string for the method type, as per JVMS 4.3.3
+     * @return the {@linkplain MethodTypeDesc}
+     */
+    public static MethodTypeDesc constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
+                                                   String descriptor) {
+        return MethodTypeDesc.ofDescriptor(descriptor);
     }
 
     @Override
--- a/src/java.base/share/classes/java/lang/invoke/constant/DescBootstraps.java	Thu Apr 19 17:19:09 2018 -0400
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,169 +0,0 @@
-/*
- * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
- * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
- *
- * This code is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation.  Oracle designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Oracle in the LICENSE file that accompanied this code.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
- * or visit www.oracle.com if you need additional information or have any
- * questions.
- */
-package java.lang.invoke.constant;
-
-import jdk.internal.lang.annotation.Foldable;
-
-import java.lang.invoke.MethodHandles;
-
-import static java.lang.invoke.constant.ConstantDescs.CR_ClassDesc;
-import static java.lang.invoke.constant.ConstantDescs.CR_ConstantDesc;
-import static java.lang.invoke.constant.ConstantDescs.CR_DynamicConstantDesc;
-import static java.lang.invoke.constant.ConstantDescs.CR_EnumDesc;
-import static java.lang.invoke.constant.ConstantDescs.CR_MethodHandleDesc;
-import static java.lang.invoke.constant.ConstantDescs.CR_MethodTypeDesc;
-import static java.lang.invoke.constant.ConstantDescs.CR_String;
-
-/**
- * DescBoostraps
- *
- * @author Brian Goetz
- */
-public final class DescBootstraps {
-    private DescBootstraps() { }
-
-    @Foldable
-    private static final ClassDesc THIS_CLASS = ClassDesc.of("java.lang.invoke.constant.DescBootstraps");
-
-    /** Bootstrap for ClassDesc */
-    @Foldable
-    public static final ConstantMethodHandleDesc BSM_CLASSDESC
-            = ConstantDescs.ofConstantBootstrap(THIS_CLASS, "classDesc", CR_ClassDesc,
-                                                CR_String);
-
-    /** Bootstrap for MethodTypeDesc */
-    @Foldable
-    public static final ConstantMethodHandleDesc BSM_METHODTYPEDESC
-            = ConstantDescs.ofConstantBootstrap(THIS_CLASS, "methodTypeDesc", CR_MethodTypeDesc,
-                                                CR_String);
-
-    /** Bootstrap for MethodHandleDesc */
-    @Foldable
-    public static final ConstantMethodHandleDesc BSM_METHODHANDLEDESC
-            = ConstantDescs.ofConstantBootstrap(THIS_CLASS, "methodHandleDesc", CR_MethodHandleDesc,
-                                                CR_String, CR_String, CR_String, CR_String);
-
-    /** Bootstrap for DynamicConstantDesc */
-    @Foldable
-    public static final ConstantMethodHandleDesc BSM_DYNAMICCONSTANTDESC
-            = ConstantDescs.ofConstantBootstrap(THIS_CLASS, "dynamicConstantDesc", CR_DynamicConstantDesc,
-                                                CR_String, CR_String, CR_String, CR_String, CR_String,
-                                                CR_ConstantDesc.array());
-
-    /** Bootstrap for ClassDesc */
-    @Foldable
-    public static final ConstantMethodHandleDesc BSM_ENUMDESC
-            = ConstantDescs.ofConstantBootstrap(THIS_CLASS, "enumDesc", CR_EnumDesc,
-                                                CR_String, CR_String);
-
-    /**
-     * Bootstrap for ClassDesc
-     *
-     * @param lookup ignored
-     * @param name ignored
-     * @param clazz ignored
-     * @param descriptor descriptor for class
-     * @return the ClassDesc
-     */
-    public static ClassDesc classDesc(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
-                                      String descriptor) {
-        // @@@ Can fold descriptor into name channel, with encoding from BytecodeName
-        return ClassDesc.ofDescriptor(descriptor);
-    }
-
-    /**
-     * Bootstrap for MethodTypeDesc
-     *
-     * @param lookup ignored
-     * @param name ignored
-     * @param clazz ignored
-     * @param descriptor descriptor for method
-     * @return the MethodTypeDesc
-     */
-    public static MethodTypeDesc methodTypeDesc(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
-                                                String descriptor) {
-        // @@@ Can fold descriptor into name channel, with encoding from BytecodeName
-        return MethodTypeDesc.ofDescriptor(descriptor);
-    }
-
-    /**
-     * Bootstrap for MethodHandleDesc
-     *
-     * @param lookup ignored
-     * @param name ignored
-     * @param clazz ignored
-     * @param bsmKindName kind
-     * @param bsmOwner owner
-     * @param bsmName name
-     * @param bsmDesc desc
-     * @return the MethodHandleDesc
-     */
-    public static MethodHandleDesc methodHandleDesc(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
-                                                    String bsmKindName, String bsmOwner, String bsmName, String bsmDesc) {
-        return MethodHandleDesc.of(MethodHandleDesc.Kind.valueOf(bsmKindName),
-                                   ClassDesc.ofDescriptor(bsmOwner), bsmName,
-                                   MethodTypeDesc.ofDescriptor(bsmDesc));
-    }
-
-    /**
-     * Bootstrap for DynamicConstantDesc
-     *
-     * @param lookup ignored
-     * @param name ignored
-     * @param clazz ignored
-     * @param bsmOwner owner
-     * @param bsmName name
-     * @param bsmDesc desc
-     * @param invName invName
-     * @param invType invType
-     * @param args bsm args
-     * @return the DynamicConstantDesc
-     */
-    public static DynamicConstantDesc<?> dynamicConstantDesc(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
-                                                             String bsmOwner, String bsmName, String bsmDesc,
-                                                             String invName, String invType,
-                                                             ConstantDesc<?>... args) {
-        return DynamicConstantDesc.of(MethodHandleDesc.of(MethodHandleDesc.Kind.STATIC,
-                                                          ClassDesc.ofDescriptor(bsmOwner), bsmName,
-                                                          MethodTypeDesc.ofDescriptor(bsmDesc)),
-                                      invName, ClassDesc.ofDescriptor(invType), args);
-
-    }
-
-    /**
-     * Bootstrap for EnumDesc
-     *
-     * @param lookup ignored
-     * @param name ignored
-     * @param clazz ignored
-     * @param classDescriptor enum class
-     * @param constantName enum constant
-     * @return the EnumDesc
-     */
-    public static EnumDesc<?> enumDesc(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
-                                       String classDescriptor, String constantName) {
-        return EnumDesc.of(ClassDesc.ofDescriptor(classDescriptor), constantName);
-    }
-}
--- a/src/java.base/share/classes/java/lang/invoke/constant/DynamicCallSiteDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/DynamicCallSiteDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -40,7 +40,8 @@
 import static java.util.stream.Collectors.joining;
 
 /**
- * A nominal descriptor for an {@code invokedynamic} call site.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for an
+ * {@code invokedynamic} call site.
  */
 @SuppressWarnings("rawtypes")
 public final class DynamicCallSiteDesc {
@@ -51,19 +52,22 @@
     private final MethodTypeDesc invocationType;
 
     /**
-     * Construct a nominal descriptor for an {@code invokedynamic} call site
+     * Create a nominal descriptor for an {@code invokedynamic} call site.
      *
-     * @param bootstrapMethod The bootstrap method for the {@code invokedynamic}
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the {@code invokedynamic}
      * @param invocationName The name that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}, as per
+     *                       JVMS 4.2.2
+     * @param invocationType a {@link MethodTypeDesc} describing the invocation
+     *                       type that would appear in the {@code NameAndType}
      *                       operand of the {@code invokedynamic}
-     * @param invocationType The invocation type that would appear in the
-     * {@code NameAndType} operand of the {@code invokedynamic}
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @throws NullPointerException if any parameter is null
-     * @throws IllegalArgumentException if the bootstrap method is not a
-     * {@link ConstantMethodHandleDesc}
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the invocation name has the incorrect
+     * format
      */
     private DynamicCallSiteDesc(ConstantMethodHandleDesc bootstrapMethod,
                                 String invocationName,
@@ -78,44 +82,22 @@
     }
 
     /**
-     * Return a nominal descriptor for an {@code invokedynamic} call site.  If
-     * the bootstrap method corresponds to a well-known bootstrap, for which a
-     * more specific nominal descriptor invocationType exists, the more specific nominal
-     * descriptor invocationType is returned.
+     * Create a nominal descriptor for an {@code invokedynamic} call site.
      *
-     * @param bootstrapMethod The bootstrap method for the {@code invokedynamic}
-     * @param invocationName The invocationName that would appear in the
-     * {@code NameAndType} operand of the {@code invokedynamic}
-     * @param invocationType The invocation invocationType that would appear in
-     * the {@code NameAndType} operand of the {@code invokedynamic}
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
-     * @return the nominal descriptor
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the {@code invokedynamic}
+     * @param invocationName The name that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}, as per
+     *                       JVMS 4.2.2
+     * @param invocationType a {@link MethodTypeDesc} describing the invocation
+     *                       type that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @throws NullPointerException if any parameter is null
-     */
-    @Foldable
-    public static DynamicCallSiteDesc ofCanonical(ConstantMethodHandleDesc bootstrapMethod,
-                                                  String invocationName,
-                                                  MethodTypeDesc invocationType,
-                                                  ConstantDesc<?>... bootstrapArgs) {
-        return new DynamicCallSiteDesc(bootstrapMethod,
-                                       invocationName, invocationType,
-                                       bootstrapArgs)
-                .canonicalize();
-    }
-
-    /**
-     * Return a nominal descriptor for an {@code invokedynamic} call site.
-     *
-     * @param bootstrapMethod The bootstrap method for the {@code invokedynamic}
-     * @param invocationName The invocationName that would appear in the
-     * {@code NameAndType} operand of the {@code invokedynamic}
-     * @param invocationType The invocation invocationType that would appear in
-     * the {@code NameAndType} operand of the {@code invokedynamic}
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
-     * @return the nominal descriptor
-     * @throws NullPointerException if any parameter is null
+     * @throws IllegalArgumentException if the invocation name has the incorrect
+     * format
      */
     @Foldable
     public static DynamicCallSiteDesc of(ConstantMethodHandleDesc bootstrapMethod,
@@ -126,7 +108,7 @@
     }
 
     /**
-     * Return a nominal descriptor for an {@code invokedynamic} call site whose
+     * Create a nominal descriptor for an {@code invokedynamic} call site whose
      * bootstrap method has no static arguments.
      *
      * @param bootstrapMethod The bootstrap method for the {@code invokedynamic}
@@ -145,15 +127,18 @@
     }
 
     /**
-     * Return a nominal descriptor for an {@code invokedynamic} call site whose
+     * Create a nominal descriptor for an {@code invokedynamic} call site whose
      * bootstrap method has no static arguments and for which the name parameter
      * is {@link ConstantDescs#DEFAULT_NAME}.
      *
-     * @param bootstrapMethod The bootstrap method for the {@code invokedynamic}
-     * @param invocationType The invocation type that would appear in
-     * the {@code NameAndType} operand of the {@code invokedynamic}
-     * @return the nominal descriptor
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the {@code invokedynamic}
+     * @param invocationType a {@link MethodTypeDesc} describing the invocation
+     *                       type that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}
      * @throws NullPointerException if any parameter is null
+     * @throws IllegalArgumentException if the invocation name has the incorrect
+     * format
      */
     @Foldable
     public static DynamicCallSiteDesc of(ConstantMethodHandleDesc bootstrapMethod,
@@ -166,8 +151,9 @@
      * bootstrap method, name, and invocation type are the same as this one, but
      * with the specified bootstrap arguments.
      *
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @return the nominal descriptor
      * @throws NullPointerException if any parameter is null
      */
@@ -181,12 +167,16 @@
      * bootstrap and bootstrap arguments are the same as this one, but with the
      * specified invocationName and invocation invocationType
      *
-     * @param invocationName The invocationName that would appear in the
-     * {@code NameAndType} operand of the {@code invokedynamic}
-     * @param invocationType The invocation invocationType that would appear in
-     * the {@code NameAndType} operand of the {@code invokedynamic}
+     * @param invocationName The name that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}, as per
+     *                       JVMS 4.2.2
+     * @param invocationType a {@link MethodTypeDesc} describing the invocation
+     *                       type that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}
      * @return the nominal descriptor
      * @throws NullPointerException if any parameter is null
+     * @throws IllegalArgumentException if the invocation name has the incorrect
+     * format
      */
     @Foldable
     public DynamicCallSiteDesc withNameAndType(String invocationName,
@@ -200,8 +190,9 @@
     }
 
     /**
-     * Returns the invocation name that would appear in the {@code NameAndType} operand
-     * of the {@code invokedynamic}
+     * Returns the invocation name that would appear in the {@code NameAndType}
+     * operand of the {@code invokedynamic}.
+     * \
      * @return the invocation name
      */
     @Foldable
@@ -210,8 +201,9 @@
     }
 
     /**
-     * Returns the invocation type that would appear in the {@code NameAndType} operand
-     * of the {@code invokedynamic}
+     * Returns a {@link MethodTypeDesc} describing the invocation type that
+     * would appear in the {@code NameAndType} operand of the {@code invokedynamic}.
+     *
      * @return the invocation type
      */
     @Foldable
@@ -220,14 +212,18 @@
     }
 
     /**
-     * Returns the bootstrap method for the {@code invokedynamic}
+     * Returns a {@link MethodHandleDesc} descripbing the bootstrap method for
+     * the {@code invokedynamic}.
+     *
      * @return the bootstrap method for the {@code invokedynamic}
      */
     @Foldable
     public MethodHandleDesc bootstrapMethod() { return bootstrapMethod; }
 
     /**
-     * Returns the bootstrap arguments for the {@code invokedynamic}
+     * Returns {@link ConstantDesc}s describing the bootstrap arguments for the
+     * {@code invokedynamic}.
+     *
      * @return the bootstrap arguments for the {@code invokedynamic}
      */
     public ConstantDesc<?>[] bootstrapArgs() { return bootstrapArgs.clone(); }
--- a/src/java.base/share/classes/java/lang/invoke/constant/DynamicConstantDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/DynamicConstantDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -26,6 +26,7 @@
 
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodHandles;
+import java.lang.invoke.VarHandle;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
@@ -36,21 +37,32 @@
 
 import jdk.internal.lang.annotation.Foldable;
 
+import static java.lang.invoke.constant.ConstantDescs.CR_ConstantDesc;
 import static java.lang.invoke.constant.ConstantDescs.CR_DynamicConstantDesc;
+import static java.lang.invoke.constant.ConstantDescs.CR_String;
 import static java.lang.invoke.constant.ConstantUtils.validateMemberName;
 import static java.util.Objects.requireNonNull;
 import static java.util.stream.Collectors.joining;
 
 /**
- * A nominal descriptor for a dynamic constant (one described in the constant
- * pool with {@code Constant_Dynamic_info}.)
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * dynamic constant (one described in the constant pool with
+ * {@code Constant_Dynamic_info}.)
  *
  * <p>Concrete subtypes of {@linkplain DynamicConstantDesc} must be
  * <a href="../doc-files/ValueBased.html">value-based</a>.
  *
  * @param <T> the type of the dynamic constant
  */
-public abstract class DynamicConstantDesc<T> implements ConstantDesc<T>, Constable<ConstantDesc<T>> {
+public abstract class DynamicConstantDesc<T>
+        implements ConstantDesc<T>, Constable<ConstantDesc<T>> {
+
+    @Foldable
+    private static final ConstantMethodHandleDesc BSM_DYNAMICCONSTANTDESC
+            = ConstantDescs.ofConstantBootstrap(ClassDesc.of("java.lang.invoke.constant", "DynamicConstantDesc"),
+                                                "constantBootstrap",
+                                                CR_DynamicConstantDesc,
+                                                CR_String, CR_String, CR_String, CR_String, CR_String, CR_ConstantDesc.array());
 
     private final ConstantMethodHandleDesc bootstrapMethod;
     private final ConstantDesc<?>[] bootstrapArgs;
@@ -75,19 +87,22 @@
     );
 
     /**
-     * Construct a nominal descriptor for a dynamic constant
+     * Create a nominal descriptor for a dynamic constant.
      *
-     * @param bootstrapMethod The bootstrap method for the constant
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
      * @param constantName The name that would appear in the {@code NameAndType}
-     *                     operand of the {@code LDC} for this constant
-     * @param constantType The type that would appear in the {@code NameAndType}
-     *                     operand of the {@code LDC} for this constant
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
+     *                     operand of the {@code LDC} for this constant, as per
+     *                     JVMS 4.2.2
+     * @param constantType a {@link ConstantMethodHandleDesc} describing the type
+     *                     that would appear in the {@code NameAndType} operand
+     *                     of the {@code LDC} for this constant
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if the bootstrap method is not a
-     * {@link ConstantMethodHandleDesc}
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     protected DynamicConstantDesc(ConstantMethodHandleDesc bootstrapMethod,
                                   String constantName,
@@ -105,9 +120,11 @@
     /**
      * Return a nominal descriptor for a dynamic constant whose bootstrap, invocation
      * name, and invocation type are the same as this one, but with the specified
-     * bootstrap arguments
+     * bootstrap arguments.
      *
-     * @param bootstrapArgs the bootstrap arguments
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
      */
@@ -116,31 +133,45 @@
         return DynamicConstantDesc.of(bootstrapMethod, constantName, constantType, bootstrapArgs);
     }
 
-    // TODO Better description needed
     /**
-     * Return a nominal descriptor for a dynamic constant.  If the bootstrap
-     * corresponds to a well-known bootstrap, for which a more specific nominal
-     * descriptor type (e.g., ClassDesc) is available, then the more specific
-     * nominal descriptor will be returned.
+     * Return a nominal descriptor for a dynamic constant, transforming it into
+     * a more specific type if the constant bootstrap is a well-known one and a
+     * more specific nominal descriptor type (e.g., ClassDesc) is available.
+     *
+     * <p>Classes whose {@link Constable#describeConstable()} method produces
+     * a {@linkplain DynamicConstantDesc} with a well-known bootstrap including
+     * {@link Class} (for instances describing primitive types), {@link Enum},
+     * and {@link VarHandle}.
+     *
+     * <p>Bytecode-reading APIs that process the constant pool and wish to expose
+     * entries as {@link ConstantDesc} to their callers should generally use this
+     * method in preference to {@link #of(ConstantMethodHandleDesc, String, ClassDesc, ConstantDesc[])}
+     * because this may result in a more specific type that can be provided to
+     * callers.
      *
      * @param <T> the type of the dynamic constant
-     * @param bootstrapMethod The bootstrap method for the constant
-     * @param name The name that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
-     * @param type The type that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
+     * @param constantName The name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant, as per
+     *                     JVMS 4.2.2
+     * @param constantType a {@link ConstantMethodHandleDesc} describing the type
+     *                     that would appear in the {@code NameAndType} operand
+     *                     of the {@code LDC} for this constant
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     @Foldable
     public static<T> ConstantDesc<T> ofCanonical(ConstantMethodHandleDesc bootstrapMethod,
-                                                 String name,
-                                                 ClassDesc type,
+                                                 String constantName,
+                                                 ClassDesc constantType,
                                                  ConstantDesc<?>[] bootstrapArgs) {
-        return DynamicConstantDesc.<T>of(bootstrapMethod, name, type, bootstrapArgs)
+        return DynamicConstantDesc.<T>of(bootstrapMethod, constantName, constantType, bootstrapArgs)
                 .canonicalize();
     }
 
@@ -160,23 +191,28 @@
      * Return a nominal descriptor for a dynamic constant.
      *
      * @param <T> the type of the dynamic constant
-     * @param bootstrapMethod The bootstrap method for the constant
-     * @param name The name that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
-     * @param type The type that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
-     * @param bootstrapArgs The static arguments to the bootstrap, that would
-     *                      appear in the {@code BootstrapMethods} attribute
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
+     * @param constantName The name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant, as per
+     *                     JVMS 4.2.2
+     * @param constantType a {@link ConstantMethodHandleDesc} describing the type
+     *                     that would appear in the {@code NameAndType} operand
+     *                     of the {@code LDC} for this constant
+     * @param bootstrapArgs {@link ConstantDesc}s describing the static arguments
+     *                      to the bootstrap, that would appear in the
+     *                      {@code BootstrapMethods} attribute
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     @Foldable
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
-                                               String name,
-                                               ClassDesc type,
+                                               String constantName,
+                                               ClassDesc constantType,
                                                ConstantDesc<?>[] bootstrapArgs) {
-        return new DynamicConstantDesc<>(bootstrapMethod, name, type, bootstrapArgs) { };
+        return new DynamicConstantDesc<T>(bootstrapMethod, constantName, constantType, bootstrapArgs) { };
     }
 
     /**
@@ -184,39 +220,44 @@
      * no static arguments.
      *
      * @param <T> the type of the dynamic constant
-     * @param bootstrapMethod The bootstrap method for the constant
-     * @param name The name that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
-     * @param type The type that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
+     * @param constantName The name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant, as per
+     *                     JVMS 4.2.2
+     * @param constantType a {@link ConstantMethodHandleDesc} describing the type
+     *                     that would appear in the {@code NameAndType} operand
+     *                     of the {@code LDC} for this constant
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     @Foldable
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
-                                               String name,
-                                               ClassDesc type) {
-        return DynamicConstantDesc.of(bootstrapMethod, name, type, ConstantUtils.EMPTY_CONSTANTDESC);
+                                               String constantName,
+                                               ClassDesc constantType) {
+        return DynamicConstantDesc.of(bootstrapMethod, constantName, constantType, ConstantUtils.EMPTY_CONSTANTDESC);
     }
 
     /**
      * Return a nominal descriptor for a dynamic constant whose bootstrap has
      * no static arguments, and for which the name parameter
-     * is {@link ConstantDescs#DEFAULT_NAME}
+     * is {@link ConstantDescs#DEFAULT_NAME}.
      *
      * @param <T> the type of the dynamic constant
-     * @param bootstrapMethod The bootstrap method for the constant
-     * @param type The type that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
+     * @param constantType a {@link ConstantMethodHandleDesc} describing the type
+     *                     that would appear in the {@code NameAndType} operand
+     *                     of the {@code LDC} for this constant
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if {@code name.length()} is zero
      */
     @Foldable
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
-                                               ClassDesc type) {
-        return of(bootstrapMethod, ConstantDescs.DEFAULT_NAME, type);
+                                               ClassDesc constantType) {
+        return of(bootstrapMethod, ConstantDescs.DEFAULT_NAME, constantType);
     }
 
     /**
@@ -225,17 +266,20 @@
      * bootstrap method return type.
      *
      * @param <T> the type of the dynamic constant
-     * @param bootstrapMethod The bootstrap method for the constant
-     * @param name The name that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
+     * @param constantName The name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant, as per
+     *                     JVMS 4.2.2
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     @Foldable
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
-                                               String name) {
-        return of(bootstrapMethod, name, bootstrapMethod.methodType().returnType());
+                                               String constantName) {
+        return of(bootstrapMethod, constantName, bootstrapMethod.methodType().returnType());
     }
 
     /**
@@ -244,10 +288,12 @@
      * and whose type parameter is always the same as the bootstrap method return type.
      *
      * @param <T> the type of the dynamic constant
-     * @param bootstrapMethod The bootstrap method for the constant
+     * @param bootstrapMethod a {@link ConstantMethodHandleDesc} describing the
+     *                        bootstrap method for the constant
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
-     * @throws IllegalArgumentException if {@code name.length()} is zero
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     @Foldable
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod) {
@@ -255,9 +301,10 @@
     }
 
     /**
-     * returns The name that would appear in the {@code NameAndType} operand
+     * Returns The name that would appear in the {@code NameAndType} operand
      *             of the {@code LDC} for this constant
-     * @return the name
+     *
+     * @return the constant name
      */
     @Foldable
     public String constantName() {
@@ -265,9 +312,10 @@
     }
 
     /**
-     * returns The type that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
-     * @return the type
+     * Returns a {@link ClassDesc} describing the type that would appear in the
+     * {@code NameAndType} operand of the {@code LDC} for this constant.
+     *
+     * @return the constant type
      */
     @Foldable
     public ClassDesc constantType() {
@@ -275,7 +323,9 @@
     }
 
     /**
-     * Returns the bootstrap method for this constant
+     * Returns a {@link MethodHandleDesc} describing the bootstrap method for
+     * this constant
+     *
      * @return the bootstrap method
      */
     @Foldable
@@ -293,7 +343,8 @@
 
     /**
      * Returns the bootstrap arguments for this constant as a {@link List}
-     * @return the bootstrap arguments
+     *
+     * @return a {@link List} of the bootstrap arguments, described as {@link ConstantDesc}
      */
     public List<ConstantDesc<?>> bootstrapArgsList() {
         return List.of(bootstrapArgs);
@@ -356,10 +407,41 @@
         args[3] = constantName;
         args[4] = constantType.descriptorString();
         System.arraycopy(bootstrapArgs, 0, args, 5, bootstrapArgs.length);
-        return Optional.of(DynamicConstantDesc.of(DescBootstraps.BSM_DYNAMICCONSTANTDESC, ConstantDescs.DEFAULT_NAME,
+        return Optional.of(DynamicConstantDesc.of(BSM_DYNAMICCONSTANTDESC, ConstantDescs.DEFAULT_NAME,
                                                   CR_DynamicConstantDesc, args));
     }
 
+    /**
+     * Constant bootstrap method for representing a {@linkplain DynamicConstantDesc}
+     * in the constant pool of a classfile.
+     *
+     * @param lookup ignored
+     * @param name ignored
+     * @param clazz ignored
+     * @param bsmOwner A field type descriptor for the class declaring the
+     *                 bootstrap method, as per JVMS 4.3.2
+     * @param bsmName The name of the bootstrap method, as per JVMS 4.2.2
+     * @param bsmDesc A method type descriptor for bootstrap method, as per JVMS 4.3.3
+     * @param constantName The name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant, as per
+     *                     JVMS 4.2.2
+     * @param constantType a field type descriptor string describing the type
+     *                     that would appear in the {@code NameAndType} operand
+     *                     of the {@code LDC} for this constant, as per JVMS 4.3.2
+     * @param args The static arguments to the bootstrap method
+     * @return the {@linkplain DynamicConstantDesc}
+     */
+    public static DynamicConstantDesc<?> constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
+                                                           String bsmOwner, String bsmName, String bsmDesc,
+                                                           String constantName, String constantType,
+                                                           ConstantDesc<?>... args) {
+        return DynamicConstantDesc.of(MethodHandleDesc.of(MethodHandleDesc.Kind.STATIC,
+                                                          ClassDesc.ofDescriptor(bsmOwner), bsmName,
+                                                          MethodTypeDesc.ofDescriptor(bsmDesc)),
+                                      constantName, ClassDesc.ofDescriptor(constantType), args);
+
+    }
+
     @Override
     public final boolean equals(Object o) {
         if (this == o) return true;
--- a/src/java.base/share/classes/java/lang/invoke/constant/EnumDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/EnumDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -30,21 +30,29 @@
 import java.util.Optional;
 
 import static java.lang.invoke.constant.ConstantDescs.CR_EnumDesc;
+import static java.lang.invoke.constant.ConstantDescs.CR_String;
 import static java.lang.invoke.constant.ConstantUtils.validateMemberName;
 import static java.util.Objects.requireNonNull;
 
 /**
- * A nominal descriptor for an {@code enum} constant.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for an
+ * {@code enum} constant.
  *
  * @param <E> the type of the enum constant
  */
-public final class EnumDesc<E extends Enum<E>> extends DynamicConstantDesc<E> {
+public final class EnumDesc<E extends Enum<E>>
+        extends DynamicConstantDesc<E> {
+
+    @Foldable
+    private static final ConstantMethodHandleDesc BSM_ENUMDESC
+            = ConstantDescs.ofConstantBootstrap(ClassDesc.of("java.lang.invoke.constant", "EnumDesc"),
+                                                "constantBootstrap", CR_EnumDesc, CR_String, CR_String);
 
     /**
-     * Construct a nominal descriptor for the specified enum class and name
+     * Construct a nominal descriptor for the specified {@code enum} class and name.
      *
-     * @param constantType the enum class
-     * @param constantName the name of the enum constant
+     * @param constantType a {@link ClassDesc} describing the {@code enum} class
+     * @param constantName the name of the enum constant, as per JVMS 4.2.2
      * @throws NullPointerException if any argument is null
      */
     private EnumDesc(ClassDesc constantType, String constantName) {
@@ -52,10 +60,10 @@
     }
 
     /**
-     * Return a nominal descriptor for the specified enum class and name
+     * Return a nominal descriptor for the specified {@code enum} class and name
      *
      * @param <E> the type of the enum constant
-     * @param enumClass the enum class
+     * @param enumClass a {@link ClassDesc} describing the {@code enum} class
      * @param constantName the name of the enum constant, as per JVMS 4.2.2
      * @return the nominal descriptor
      * @throws NullPointerException if any argument is null
@@ -75,10 +83,27 @@
 
     @Override
     public Optional<? extends ConstantDesc<? super ConstantDesc<E>>> describeConstable(MethodHandles.Lookup lookup) {
-        return Optional.of(DynamicConstantDesc.of(DescBootstraps.BSM_ENUMDESC, CR_EnumDesc)
+        return Optional.of(DynamicConstantDesc.of(BSM_ENUMDESC, CR_EnumDesc)
                                               .withArgs(constantType().descriptorString(), constantName()));
     }
 
+    /**
+     * Constant bootstrap method for representing an {@linkplain EnumDesc} in
+     * the constant pool of a classfile.
+     *
+     * @param lookup ignored
+     * @param name ignored
+     * @param clazz ignored
+     * @param classDescriptor A field type descriptor for the enum class, as
+     *                        per JVMS 4.3.2
+     * @param constantName The name of the {@code enum} constant
+     * @return the {@linkplain EnumDesc}
+     */
+    public static EnumDesc<?> constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
+                                                String classDescriptor, String constantName) {
+        return EnumDesc.of(ClassDesc.ofDescriptor(classDescriptor), constantName);
+    }
+
     @Override
     public String toString() {
         return String.format("EnumDesc[%s.%s]", constantType().displayName(), constantName());
--- a/src/java.base/share/classes/java/lang/invoke/constant/MethodHandleDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/MethodHandleDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -43,12 +43,13 @@
 import static java.lang.invoke.constant.MethodHandleDesc.Kind.CONSTRUCTOR;
 
 /**
- * A nominal descriptor for a {@link MethodHandle} constant.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * {@link MethodHandle} constant.
  */
 public interface MethodHandleDesc
         extends ConstantDesc<MethodHandle>, Constable<ConstantDesc<MethodHandle>> {
     /**
-     * Kinds of method handle descriptors
+     * Kinds of method handles that can be described with {@linkplain MethodHandleDesc}.
      */
     public enum Kind {
         /** A method handle for a method invoked as with {@code invokestatic} */
@@ -82,7 +83,7 @@
 
 
     /**
-     * Return a {@linkplain MethodHandleDesc} corresponding to an invocation of a
+     * Create a {@linkplain MethodHandleDesc} corresponding to an invocation of a
      * declared method, invocation of a constructor, or access to a field.
      *
      * <p>If {@code kind} is {@code CONSTRUCTOR}, the name is ignored and the return
@@ -96,12 +97,16 @@
      * and {@link #ofConstructor(ClassDesc, ClassDesc...)} may be more convenient.
      *
      * @param kind The kind of method handle to be described
-     * @param clazz the class declaring the method, constructor, or field
+     * @param clazz a {@link ClassDesc} describing the class containing the
+     *              method, constructor, or field
      * @param name the name of the method or field (ignored if {@code kind} is
      * {@code CONSTRUCTOR}), as per JVMS 4.2.2
-     * @param type the invocation type of the method handle
+     * @param type a {@link MethodTypeDesc} describing the invocation type of
+     *             the method handle
      * @return the {@linkplain MethodHandleDesc}
-     * @throws NullPointerException if any of the non-ignored arguments are null
+     * @throws NullPointerException if any non-ignored arguments are null
+     * @throws IllegalArgumentException if the {@code name} has the incorrect
+     * format
      */
     @Foldable
     static ConstantMethodHandleDesc of(Kind kind,
@@ -112,7 +117,7 @@
     }
 
     /**
-     * Return a {@linkplain MethodHandleDesc} corresponding to an invocation of a
+     * Create a {@linkplain MethodHandleDesc} corresponding to an invocation of a
      * declared method, invocation of a constructor, or access to a field.
      *
      * <p>If {@code kind} is {@code CONSTRUCTOR}, the name is ignored and the return
@@ -125,10 +130,11 @@
      * the appropriate invocation given the type of the field.
      *
      * @param kind The kind of method handle to be described
-     * @param clazz the class declaring the method, constructor, or field
+     * @param clazz a {@link ClassDesc} describing the class containing the
+     *              method, constructor, or field
      * @param name the name of the method or field (ignored if {@code kind} is
      * {@code CONSTRUCTOR}), as per JVMS 4.2.2
-     * @param descriptorString method descriptor string for the invocation type
+     * @param descriptorString a method descriptor string for the invocation type
      * of the method handle, as per JVMS 4.3.3
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the non-ignored arguments are null
@@ -142,7 +148,7 @@
     }
 
     /**
-     * Return a {@linkplain MethodHandleDesc} corresponding to an invocation of a
+     * Create a {@linkplain MethodHandleDesc} corresponding to an invocation of a
      * declared method, invocation of a constructor, or access to a field.
      *
      * <p>If {@code kind} is {@code CONSTRUCTOR}, the name is ignored and the return
@@ -155,11 +161,14 @@
      * the appropriate invocation given the type of the field.
      *
      * @param kind The kind of method handle to be described
-     * @param clazz the class declaring the method, constructor, or field
+     * @param clazz a {@link ClassDesc} describing the class containing the
+     *              method, constructor, or field
      * @param name the name of the method or field (ignored if {@code kind} is
      * {@code CONSTRUCTOR}), as per JVMS 4.2.2
-     * @param returnType the return type of the method handle
-     * @param paramTypes the parameter types of the method handle
+     * @param returnType a {@link ClassDesc} describing the return type of the
+     *                   method handle
+     * @param paramTypes {@link ClassDesc}s describing the parameter types of
+     *                                    the method handle
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the non-ignored arguments are null
      */
@@ -173,13 +182,15 @@
     }
 
     /**
-     * Return a {@linkplain MethodHandleDesc} corresponding to accessing a field
+     * Create a {@linkplain MethodHandleDesc} corresponding to a method handle
+     * that accesses a field.
      *
-     * @param kind the kind of the method handle; must be one of {@code GETTER},
+     * @param kind the kind of the method handle to be described; must be one of {@code GETTER},
      *             {@code SETTER}, {@code STATIC_GETTER}, or {@code STATIC_SETTER}
-     * @param clazz the class declaring the field
+     * @param clazz a {@link ClassDesc} describing the class containing the
+     *              method, constructor, or field
      * @param fieldName the name of the field, as per JVMS 4.2.2
-     * @param fieldType the type of the field
+     * @param fieldType a {@link ClassDesc} describing the type of the field
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the arguments are null
      */
@@ -203,8 +214,10 @@
     /**
      * Return a {@linkplain MethodHandleDesc} corresponding to invocation of a constructor
      *
-     * @param clazz the class declaring the constuctor
-     * @param paramTypes the parameter types of the constructor
+     * @param clazz a {@link ClassDesc} describing the class containing the
+     *              method, constructor, or field
+     * @param paramTypes {@link ClassDesc}s describing the parameter types of
+     *                   the constructor
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the arguments are null
      */
@@ -216,21 +229,23 @@
     }
 
     /**
-     * Return the type of the method handle described by this nominal descriptor
-     * @return the method type
-     */
-    @Foldable
-    MethodTypeDesc methodType();
-
-    /**
      * Return a {@linkplain MethodHandleDesc} that describes this method handle
      * adapted to a different type, as if by {@link MethodHandle#asType(MethodType)}.
      *
-     * @param type the new type
-     * @return the adapted descriptor
+     * @param type a {@link MethodHandleDesc} describing the new method type
+     * @return a {@linkplain MethodHandleDesc} for the adapted method handle
      */
     @Foldable
     default MethodHandleDesc asType(MethodTypeDesc type) {
         return (methodType().equals(type)) ? this : new AsTypeMethodHandleDesc(this, type);
     }
+
+    /**
+     * Return a {@link MethodTypeDesc} describing the type of the method handle
+     * described by this nominal descriptor
+     *
+     * @return a {@linkplain MethodHandleDesc} describing the method handle type
+     */
+    @Foldable
+    MethodTypeDesc methodType();
 }
--- a/src/java.base/share/classes/java/lang/invoke/constant/MethodTypeDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/MethodTypeDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -34,14 +34,17 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * A nominal descriptor for a {@linkplain MethodType} constant.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * {@linkplain MethodType} constant.
  */
-public interface MethodTypeDesc extends ConstantDesc<MethodType>, Constable<ConstantDesc<MethodType>> {
+public interface MethodTypeDesc
+        extends ConstantDesc<MethodType>, Constable<ConstantDesc<MethodType>> {
     /**
-     * Create a {@linkplain MethodTypeDesc} from a method descriptor string
+     * Create a {@linkplain MethodTypeDesc} given a method descriptor string
      *
      * @param descriptor a method descriptor string, as per JVMS 4.3.3
      * @return a {@linkplain MethodTypeDesc} describing the desired method type
+     * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalArgumentException if the descriptor string is not a valid
      * method descriptor
      */
@@ -51,21 +54,23 @@
     }
 
     /**
-     * Returns a {@linkplain MethodTypeDesc} for the specified return type and
-     * parameter types.
+     * Returns a {@linkplain MethodTypeDesc} given the return type and parameter
+     * types.
      *
-     * @param returnDescriptor a {@linkplain ClassDesc} describing the return type
-     * @param paramDescriptors {@linkplain ClassDesc}s describing the argument types
+     * @param returnDesc a {@linkplain ClassDesc} describing the return type
+     * @param paramDescs {@linkplain ClassDesc}s describing the argument types
      * @return a {@linkplain MethodTypeDesc} describing the desired method type
+     * @throws NullPointerException if any argument is {@code null}
      */
     @Foldable
-    static MethodTypeDesc of(ClassDesc returnDescriptor, ClassDesc... paramDescriptors) {
-        return new ConstantMethodTypeDesc(returnDescriptor, paramDescriptors);
+    static MethodTypeDesc of(ClassDesc returnDesc, ClassDesc... paramDescs) {
+        return new ConstantMethodTypeDesc(returnDesc, paramDescs);
     }
 
     /**
      * Get the return type of the method type described by this {@linkplain MethodTypeDesc}
-     * @return the return type
+     *
+     * @return a {@link ClassDesc} describing the return type of the method type
      */
     @Foldable
     ClassDesc returnType();
@@ -83,7 +88,7 @@
      * described by this {@linkplain MethodTypeDesc}
      *
      * @param index the index of the parameter to retrieve
-     * @return the parameter type
+     * @return a {@link ClassDesc} describing the desired parameter type
      * @throws IndexOutOfBoundsException if the index is outside the half-open
      * range {[0, parameterCount())}
      */
@@ -91,37 +96,38 @@
     ClassDesc parameterType(int index);
 
     /**
-     * Get the parameter types as a {@link List}
+     * Get the parameter types as a {@link List}.
      *
-     * @return the parameter types
+     * @return a {@link List} of {@link ClassDesc} describing the parameter types
      */
     List<ClassDesc> parameterList();
 
     /**
-     * Get the parameter types as an array
+     * Get the parameter types as an array.
      *
-     * @return the parameter types
+     * @return an array of {@link ClassDesc} describing the parameter types
      */
     ClassDesc[] parameterArray();
 
     /**
      * Return a {@linkplain MethodTypeDesc} that is identical to
-     * this one, except with the specified return type
+     * this one, except with the specified return type.
      *
-     * @param returnType the new return type
-     * @return the new method type descriptor
+     * @param returnType a {@link ClassDesc} describing the new return type
+     * @return a {@linkplain MethodTypeDesc} describing the desired method type
+     * @throws NullPointerException if any argument is {@code null}
      */
     @Foldable
     MethodTypeDesc changeReturnType(ClassDesc returnType);
 
     /**
      * Return a {@linkplain MethodTypeDesc} that is identical to this one,
-     * except that a single parameter type has been changed to the provided
-     * value
+     * except that a single parameter type has been changed to the specified type.
      *
      * @param index the index of the parameter to change
-     * @param paramType the new parameter type
-     * @return the new method type descriptor
+     * @param paramType a {@link ClassDesc} describing the new parameter type
+     * @return a {@linkplain MethodTypeDesc} describing the desired method type
+     * @throws NullPointerException if any argument is {@code null}
      * @throws IndexOutOfBoundsException if the index is outside the half-open
      * range {[0, parameterCount)}
      */
@@ -130,11 +136,11 @@
 
     /**
      * Return a {@linkplain MethodTypeDesc} that is identical to this one,
-     * except that a range of parameter types have been removed
+     * except that a range of parameter types have been removed.
      *
      * @param start the index of the first parameter to remove
      * @param end the index after the last parameter to remove
-     * @return the new method type descriptor
+     * @return a {@linkplain MethodTypeDesc} describing the desired method type
      * @throws IndexOutOfBoundsException if {@code start} is outside the half-open
      * range {[0, parameterCount)}, or {@code end} is outside the closed range
      * {@code [0, parameterCount]}
@@ -144,11 +150,13 @@
 
     /**
      * Return a {@linkplain MethodTypeDesc} that is identical to this one,
-     * except that a range of additional parameter types have been inserted
+     * except that a range of additional parameter types have been inserted.
      *
      * @param pos the index at which to insert the first inserted parameter
-     * @param paramTypes the new parameter types to insert
-     * @return the new method type descriptor
+     * @param paramTypes {@link ClassDesc}s describing the new parameter types
+     *                   to insert
+     * @return a {@linkplain MethodTypeDesc} describing the desired method type
+     * @throws NullPointerException if any argument is {@code null}
      * @throws IndexOutOfBoundsException if {@code pos} is outside the closed
      * range {[0, parameterCount]}
      */
@@ -156,7 +164,8 @@
     MethodTypeDesc insertParameterTypes(int pos, ClassDesc... paramTypes);
 
     /**
-     * Return the method type descriptor string
+     * Return the method type descriptor string, as per JVMS 4.3.3.
+     *
      * @return the method type descriptor string
      */
     default String descriptorString() {
@@ -170,6 +179,7 @@
     /**
      * Return a human-readable descriptor for this method type, using the
      * canonical names for parameter and return types
+     *
      * @return the human-readable descriptor for this method type
      */
     default String displayDescriptor() {
--- a/src/java.base/share/classes/java/lang/invoke/constant/PrimitiveClassDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/PrimitiveClassDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -34,11 +34,14 @@
 /**
  * PrimitiveClassDesc
  */
-final class PrimitiveClassDesc extends DynamicConstantDesc<Class<?>> implements ClassDesc {
+final class PrimitiveClassDesc
+        extends DynamicConstantDesc<Class<?>> implements ClassDesc {
+
     private final String descriptor;
 
     /**
-     * Create a {@linkplain ClassDesc} from a descriptor string for a primitive type
+     * Create a {@linkplain ClassDesc} given a descriptor string for a primitive
+     * type.
      *
      * @param descriptor the descriptor string, which must be a one-character
      * string corresponding to one of the nine base types as per JVMS 4.3
--- a/src/java.base/share/classes/java/lang/invoke/constant/VarHandleDesc.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/VarHandleDesc.java	Thu Apr 19 17:38:29 2018 -0400
@@ -35,7 +35,8 @@
 import static java.lang.invoke.constant.ConstantDescs.CR_VarHandleDesc;
 
 /**
- * A nominal descriptor for a {@link VarHandle} constant.
+ * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
+ * {@link VarHandle} constant.
  */
 public final class VarHandleDesc extends DynamicConstantDesc<VarHandle>
         implements Constable<ConstantDesc<VarHandle>> {
@@ -75,12 +76,15 @@
     private final ClassDesc varType;
 
     /**
-     * Construct a {@linkplain VarHandleDesc}
+     * Construct a {@linkplain VarHandleDesc} given a kind, name, and declaring
+     * class.
      *
      * @param kind the kind of of the var handle
-     * @param name the name of the field, for field var handles
-     * @param declaringClass the name of the declaring class, for field var handles
-     * @param varType the type of the variable
+     * @param name the name of the field, , as per JVMS 4.2.2, for field var
+     *             handles; otherwise ignored
+     * @param declaringClass a {@link ClassDesc} describing the declaring class,
+     *                       for field var handles
+     * @param varType a {@link ClassDesc} describing the type of the variable
      * @throws NullPointerException if any required argument is null
      */
     private VarHandleDesc(Kind kind, String name, ClassDesc declaringClass, ClassDesc varType) {
@@ -93,13 +97,14 @@
     }
 
     /**
-     * Returns a {@code VarHandleDesc} corresponding to a {@link VarHandle}
+     * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
      * for an instance field.
      *
-     * @param declaringClass the class in which the field is declared
-     * @param name the name of the field
-     * @param fieldType the type of the field
-     * @return the {@code VarHandleDesc}
+     * @param name the name of the field, as per JVMS 4.2.2
+     * @param declaringClass a {@link ClassDesc} describing the declaring class,
+     *                       for field var handles
+     * @param fieldType a {@link ClassDesc} describing the type of the field
+     * @return the {@linkplain VarHandleDesc}
      * @throws NullPointerException if any of the arguments are null
      */
     @Foldable
@@ -111,13 +116,14 @@
     }
 
     /**
-     * Returns a {@code VarHandleDesc} corresponding to a {@link VarHandle}
+     * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
      * for a static field.
      *
-     * @param declaringClass the class in which the field is declared
-     * @param name the name of the field
-     * @param fieldType the type of the field
-     * @return the {@code VarHandleDesc}
+     * @param name the name of the field, as per JVMS 4.2.2
+     * @param declaringClass a {@link ClassDesc} describing the declaring class,
+     *                       for field var handles
+     * @param fieldType a {@link ClassDesc} describing the type of the field
+     * @return the {@linkplain VarHandleDesc}
      * @throws NullPointerException if any of the arguments are null
      */
     @Foldable
@@ -129,11 +135,11 @@
     }
 
     /**
-     * Returns a {@code VarHandleDesc} corresponding to a {@link VarHandle}
+     * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
      * for for an array type.
      *
-     * @param arrayClass the type of the array
-     * @return the {@code VarHandleDesc}
+     * @param arrayClass a {@link ClassDesc} describing the type of the array
+     * @return the {@linkplain VarHandleDesc}
      * @throws NullPointerException if any of the arguments are null
      */
     @Foldable
@@ -145,7 +151,8 @@
     }
 
     /**
-     * Returns the type of the variable described by this descriptor
+     * Returns a {@link ClassDesc} describing the type of the variable described
+     * by this descriptor.
      *
      * @return the variable type
      */
@@ -154,30 +161,6 @@
         return varType;
     }
 
-    // @@@ should this be the of co-ordinate types? there by better mirroring
-    // VarHandle this makes it slightly more involved since the array VH has
-    // to inject it's index
-    /**
-     * Returns the declaring class of the variable described by this descriptor.
-     *
-     * <p>If the declaring class is an array type then the declaring class
-     * will be the component type of the array type.
-     *
-     * @return the declaring class
-     */
-    @Foldable
-    public ClassDesc declaringClass() {
-        return declaringClass;
-    }
-
-    /* @@@
-    MethodTypeDesc accessModeTypeRef(AccessMode accessMode)
-     */
-
-    /* @@@
-    MethodHandleDesc toMethodHandleRef(AccessMode accessMode)
-     */
-
     @Override
     public VarHandle resolveConstantDesc(MethodHandles.Lookup lookup)
             throws ReflectiveOperationException {
--- a/src/java.base/share/classes/java/lang/invoke/constant/package-info.java	Thu Apr 19 17:19:09 2018 -0400
+++ b/src/java.base/share/classes/java/lang/invoke/constant/package-info.java	Thu Apr 19 17:38:29 2018 -0400
@@ -41,23 +41,26 @@
  * constant pool entries in nominal form that is convenient for APIs to model
  * operands of bytecode instructions.
  *
+ * <h2><a id="nominal"></a>Nominal Descriptors</h2>
+ *
  * <p>A {@link java.lang.invoke.constant.ConstantDesc} is a description of a constant
  * value.  Such a description is the <em>nominal form</em> of the constant value;
- * it is not the value itself, but rather a "recipe" for storing the value in
- * a constant pool entry, or reconstituting the value given a class loading
- * context.  Every {@link java.lang.invoke.constant.ConstantDesc} knows how to <em>resolve</em>
- * itself -- compute the value that it describes -- via the
- * {@link java.lang.invoke.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup)}
- * method.  This allows an API which accepts {@link java.lang.invoke.constant.ConstantDesc}
+ * it is not the value itself, but rather a "recipe" for describing the value,
+ * storing the value in a constant pool entry, or reconstituting the value given
+ * a class loading context.  Every {@link java.lang.invoke.constant.ConstantDesc}
+ * knows how to <em>resolve</em> itself -- compute the value that it describes --
+ * via {@link java.lang.invoke.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup)}.
+ * This allows an API which accepts {@link java.lang.invoke.constant.ConstantDesc}
  * objects to evaluate them reflectively, provided that the classes and methods
  * referenced in their nominal description are present and accessible.
  *
  * <p>The subtypes of of {@link java.lang.invoke.constant.ConstantDesc} describe various kinds
  * of constant values.  For each type of loadable constant pool entry defined in JVMS 4.4,
  * there is a corresponding subtype of {@link java.lang.invoke.constant.ConstantDesc}:
- * {@code ConstantClassDesc}, {@code ConstantMethodTypeDesc},
- * {@code ConstantMethodHandleDesc}, {@code String}, {@code Integer}, {@code Long},
- * {@code Float}, {@code Double}, and {@code DynamicConstantDesc}.  These classes
+ * {@link java.lang.invoke.constant.ConstantClassDesc}, {@link java.lang.invoke.constant.ConstantMethodTypeDesc},
+ * {@link java.lang.invoke.constant.ConstantMethodHandleDesc}, {@link java.lang.String},
+ * {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Float},
+ * {@link java.lang.Double}, and {@link java.lang.invoke.constant.DynamicConstantDesc}.  These classes
  * provides type-specific accessor methods to extract the nominal information for
  * that kind of constant.  When a bytecode-writing API encounters a {@link java.lang.invoke.constant.ConstantDesc},
  * it should examine it to see which of these types it is, cast it, extract