--- 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}