--- old/src/java.base/share/classes/java/lang/Double.java	2018-12-12 11:54:09.566329350 -0500
+++ new/src/java.base/share/classes/java/lang/Double.java	2018-12-12 11:54:09.254329361 -0500
@@ -1077,8 +1077,8 @@
     }
 
     /**
-     * Returns a nominal descriptor for this instance, which is the instance
-     * itself.
+     * Returns an {@link Optional} containing the nominal descriptor for this
+     * instance, which is the instance itself.
      *
      * @return an {@link Optional} describing the {@linkplain Double} instance
      * @since 12
--- old/src/java.base/share/classes/java/lang/Float.java	2018-12-12 11:54:10.498329317 -0500
+++ new/src/java.base/share/classes/java/lang/Float.java	2018-12-12 11:54:10.194329328 -0500
@@ -989,8 +989,8 @@
     }
 
     /**
-     * Returns a nominal descriptor for this instance, which is the instance
-     * itself.
+     * Returns an {@link Optional} containing the nominal descriptor for this
+     * instance, which is the instance itself.
      *
      * @return an {@link Optional} describing the {@linkplain Float} instance
      * @since 12
--- old/src/java.base/share/classes/java/lang/Integer.java	2018-12-12 11:54:11.258329291 -0500
+++ new/src/java.base/share/classes/java/lang/Integer.java	2018-12-12 11:54:11.022329299 -0500
@@ -1838,8 +1838,8 @@
     }
 
     /**
-     * Returns a nominal descriptor for this instance, which is the instance
-     * itself.
+     * Returns an {@link Optional} containing the nominal descriptor for this
+     * instance, which is the instance itself.
      *
      * @return an {@link Optional} describing the {@linkplain Integer} instance
      * @since 12
--- old/src/java.base/share/classes/java/lang/Long.java	2018-12-12 11:54:12.174329259 -0500
+++ new/src/java.base/share/classes/java/lang/Long.java	2018-12-12 11:54:11.870329270 -0500
@@ -1967,8 +1967,8 @@
     }
 
     /**
-     * Returns a nominal descriptor for this instance, which is the instance
-     * itself.
+     * Returns an {@link Optional} containing the nominal descriptor for this
+     * instance, which is the instance itself.
      *
      * @return an {@link Optional} describing the {@linkplain Long} instance
      * @since 12
--- old/src/java.base/share/classes/java/lang/String.java	2018-12-12 11:54:13.130329226 -0500
+++ new/src/java.base/share/classes/java/lang/String.java	2018-12-12 11:54:12.830329236 -0500
@@ -3545,8 +3545,8 @@
     }
 
     /**
-     * Returns a nominal descriptor for this instance, which is the instance
-     * itself.
+     * Returns an {@link Optional} containing the nominal descriptor for this
+     * instance, which is the instance itself.
      *
      * @return an {@link Optional} describing the {@linkplain String} instance
      * @since 12
--- old/src/java.base/share/classes/java/lang/constant/ClassDesc.java	2018-12-12 11:54:13.974329196 -0500
+++ new/src/java.base/share/classes/java/lang/constant/ClassDesc.java	2018-12-12 11:54:13.730329205 -0500
@@ -112,13 +112,13 @@
      *
      * A field type descriptor string for a non-array type is either
      * a one-letter code corresponding to a primitive type
-     * ({@code J,I,C,S,B,D,F,Z,V}), or the letter {@code L}, followed
-     * by the fully qualified binary name of a class, followed by {@code ;}.
-     * A field type descriptor for an array type is the character {@code [}
+     * ({@code "J", "I", "C", "S", "B", "D", "F", "Z", "V"}), or the letter {@code "L"}, followed
+     * by the fully qualified binary name of a class, followed by {@code ";"}.
+     * A field type descriptor for an array type is the character {@code "["}
      * followed by the field descriptor for the component type.  Examples of
-     * valid type descriptor strings include {@code Ljava/lang/String;}, {@code I},
-     * {@code [I}, {@code V}, {@code [Ljava/lang/String;}, etc.
-     * for more detail.
+     * valid type descriptor strings include {@code "Ljava/lang/String;"}, {@code "I"},
+     * {@code "[I"}, {@code "V"}, {@code "[Ljava/lang/String;"}, etc.
+     * See JVMS 4.3.2 ("Field Descriptors") for more detail.
      *
      * @param descriptor a field descriptor string
      * @return a {@linkplain ClassDesc} describing the desired class
@@ -162,6 +162,12 @@
      * Returns a {@linkplain ClassDesc} for a nested class of the class or
      * interface type described by this {@linkplain ClassDesc}.
      *
+     * @apiNote
+     *
+     * Example: If descriptor {@code d} describes the class {@code java.util.Map}, a
+     * descriptor for the class {@code java.util.Map.Entry} could be obtained
+     * by {@code d.nested("Entry")}.
+     *
      * @param nestedName the unqualified name of the nested class
      * @return a {@linkplain ClassDesc} describing the nested class
      * @throws NullPointerException if any argument is {@code null}
--- old/src/java.base/share/classes/java/lang/constant/Constable.java	2018-12-12 11:54:14.750329169 -0500
+++ new/src/java.base/share/classes/java/lang/constant/Constable.java	2018-12-12 11:54:14.510329178 -0500
@@ -65,8 +65,9 @@
  */
 public interface Constable {
     /**
-     * Returns a nominal descriptor for this instance, if one can be
-     * constructed, or an empty {@link Optional} if one cannot be constructed.
+     * Returns an {@link Optional} containing the nominal descriptor for this
+     * instance, if one can be constructed, or an empty {@link Optional}
+     * if one cannot be constructed.
      *
      * @return An {@link Optional} containing the resulting nominal descriptor,
      * or an empty {@link Optional} if one cannot be constructed.
--- old/src/java.base/share/classes/java/lang/constant/package-info.java	2018-12-12 11:54:15.534329142 -0500
+++ new/src/java.base/share/classes/java/lang/constant/package-info.java	2018-12-12 11:54:15.290329150 -0500
@@ -49,7 +49,7 @@
  * storing the value in a constant pool entry, or reconstituting the value given
  * a class loading context.  Every {@link java.lang.constant.ConstantDesc}
  * knows how to <em>resolve</em> itself -- compute the value that it describes --
- * via {@link java.lang.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup)}.
+ * via {@link java.lang.constant.ConstantDesc#resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup) ConstantDesc.resolveConstantDesc}.
  * This allows an API which accepts {@link java.lang.constant.ConstantDesc}
  * objects to evaluate them reflectively, provided that the classes and methods
  * referenced in their nominal description are present and accessible.
@@ -68,7 +68,7 @@
  * When a bytecode-reading API encounters a constant pool entry, it can
  * convert it to the appropriate type of nominal descriptor.  For dynamic
  * constants, bytecode-reading APIs may wish to use the factory
- * {@link java.lang.constant.DynamicConstantDesc#ofCanonical(DirectMethodHandleDesc, java.lang.String, ClassDesc, ConstantDesc[])},
+ * {@link java.lang.constant.DynamicConstantDesc#ofCanonical(DirectMethodHandleDesc, java.lang.String, ClassDesc, ConstantDesc[]) DynamicConstantDesc.ofCanonical},
  * which will inspect the bootstrap and, for well-known bootstraps, return
  * a more specific subtype of {@link java.lang.constant.DynamicConstantDesc}, such as
  * {@link java.lang.Enum.EnumDesc}.
--- old/src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java	2018-12-12 11:54:16.446329110 -0500
+++ new/src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java	2018-12-12 11:54:16.134329121 -0500
@@ -61,7 +61,8 @@
         boolean isArray();
 
         /**
-         * Does this field descriptor describe a primitive type?
+         * Does this field descriptor describe a primitive type (including void.)
+         *
          * @return whether this field descriptor describes a primitive type
          */
         boolean isPrimitive();
--- old/src/java.base/share/classes/java/lang/invoke/VarHandle.java	2018-12-12 11:54:17.374329078 -0500
+++ new/src/java.base/share/classes/java/lang/invoke/VarHandle.java	2018-12-12 11:54:17.074329088 -0500
@@ -1864,6 +1864,16 @@
         }
     }
 
+    /**
+     * Compare this {@linkplain VarHandle} with another object for equality.
+     * Two {@linkplain VarHandle}s are considered equal if they both describe the
+     * same instance field, both describe the same static field, both describe
+     * array elements for arrays with the same component type, or both describe
+     * the same component of an off-heap structure.
+     *
+     * @param o the other object
+     * @return Whether this {@linkplain VarHandle} is equal to the other object
+     */
     @Override
     public final boolean equals(Object o) {
         if (this == o) return true;
@@ -1883,6 +1893,12 @@
 
     abstract int internalHashCode();
 
+    /**
+     * Returns a compact textual description of this {@linkplain VarHandle},
+     * including the type of variable described, and a description of its coordinates.
+     *
+     * @return A compact textual description of this {@linkplain VarHandle}
+     */
     @Override
     public final String toString() {
         return String.format("VarHandle[varType=%s, coord=%s]",
@@ -2272,6 +2288,14 @@
             }
         }
 
+        /**
+         * Returns a compact textual description of this constant description.
+         * For a field {@linkplain VarHandle}, includes the owner, name, and type
+         * of the field, and whether it is static; for an array {@linkplain VarHandle},
+         * the name of the component type.
+         *
+         * @return A compact textual description of this descriptor
+         */
         @Override
         public String toString() {
             switch (kind) {