changeset 53472:66e1b5ed2833 jep-334

additional javadoc for overrides of Object methods, adding @implSpec to default methods, etc
author vromero
date Wed, 21 Nov 2018 15:24:03 -0500
parents 7ee0a867eeb7
children d84717b879ca edca251bb4de
files src/java.base/share/classes/java/lang/Class.java src/java.base/share/classes/java/lang/Enum.java src/java.base/share/classes/java/lang/constant/ClassDesc.java src/java.base/share/classes/java/lang/constant/ConstantDescs.java src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java src/java.base/share/classes/java/lang/constant/PrimitiveClassDescImpl.java src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java src/java.base/share/classes/java/lang/invoke/MethodType.java src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java src/java.base/share/classes/java/lang/invoke/VarHandle.java
diffstat 15 files changed, 184 insertions(+), 50 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/Class.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Class.java	Wed Nov 21 15:24:03 2018 -0500
@@ -4036,7 +4036,7 @@
     }
 
     /**
-     * Produce the type descriptor string for this class as per JVMS 4.3.2.
+     * Produce the type descriptor string for this class.
      * <p>
      * Note that this is not a strict inverse of {@link #forName};
      * distinct classes which share a common name but have different class loaders
--- a/src/java.base/share/classes/java/lang/Enum.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Enum.java	Wed Nov 21 15:24:03 2018 -0500
@@ -297,7 +297,7 @@
          * Construct a nominal descriptor for the specified {@code enum} class and name.
          *
          * @param constantType a {@link ClassDesc} describing the {@code enum} class
-         * @param constantName the name of the enum constant, as per JVMS 4.2.2
+         * @param constantName the unqualified name of the enum constant
          * @throws NullPointerException if any argument is null
          * @jvms 4.2.2 Unqualified Names
          */
@@ -310,7 +310,7 @@
          *
          * @param <E> the type of the enum constant
          * @param enumClass a {@link ClassDesc} describing the {@code enum} class
-         * @param constantName the name of the enum constant, as per JVMS 4.2.2
+         * @param constantName the unqualified name of the enum constant
          * @return the nominal descriptor
          * @throws NullPointerException if any argument is null
          * @jvms 4.2.2 Unqualified Names
--- a/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Wed Nov 21 15:24:03 2018 -0500
@@ -120,10 +120,10 @@
      * 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.  See JVMS 4.3.2
+     * {@code [I}, {@code V}, {@code [Ljava/lang/String;}, etc.
      * for more detail.
      *
-     * @param descriptor a field descriptor string, as per JVMS 4.3.2
+     * @param descriptor a field descriptor string
      * @return a {@linkplain ClassDesc} describing the desired class
      * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalArgumentException if the name string is not in the
@@ -141,6 +141,10 @@
      * Create a {@linkplain ClassDesc} for an array type whose component type
      * is described by this {@linkplain ClassDesc}.
      *
+     * @implSpec
+     * The default implementation returns the result of calling {@link #arrayType(int)},
+     * with rank equals to 1
+     *
      * @return a {@linkplain ClassDesc} describing the array type
      */
     default ClassDesc arrayType() {
@@ -151,6 +155,14 @@
      * Create a {@linkplain ClassDesc} for an array type of the specified rank,
      * whose component type is described by this {@linkplain ClassDesc}.
      *
+     * @implSpec
+     * <p>The default implementation is equivalent to:
+     * <pre>{@code
+     *     if (rank <= 0)
+     *         throw new IllegalArgumentException("rank: " + rank);
+     *     return ClassDesc.ofDescriptor("[".repeat(rank) + descriptorString());
+     * }</pre>
+     *
      * @param rank the rank of the array
      * @return a {@linkplain ClassDesc} describing the array type
      * @throws IllegalArgumentException if the rank is zero or negative
@@ -165,6 +177,15 @@
      * Create a {@linkplain ClassDesc} for an inner class of the class or
      * interface type described by this {@linkplain ClassDesc}.
      *
+     * @implSpec
+     * <p>The default implementation is equivalent to:
+     * <pre>{@code
+     *     validateMemberName(innerName);
+     *     if (!isClassOrInterface())
+     *         throw new IllegalStateException("Outer class is not a class or interface type");
+     *     return ClassDesc.ofDescriptor(String.format("%s$%s;", dropLastChar(descriptorString()), innerName));
+     * }</pre>
+     *
      * @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}
@@ -182,6 +203,16 @@
      * Create a {@linkplain ClassDesc} for an inner class of the class or
      * interface type described by this {@linkplain ClassDesc}.
      *
+     * @implSpec
+     * <p>The default implementation is equivalent to:
+     * <pre>{@code
+     *     if (!isClassOrInterface())
+     *         throw new IllegalStateException("Outer class is not a class or interface type");
+     *     return moreInnerNames.length == 0
+     *            ? inner(firstInnerName)
+     *            : inner(firstInnerName + Stream.of(moreInnerNames).collect(joining("$", "$", "")));
+     * }</pre>
+     *
      * @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
@@ -201,6 +232,10 @@
     /**
      * Returns whether this {@linkplain ClassDesc} describes an array type.
      *
+     * @implSpec
+     * The default implementation returns {@code true} if the descriptor
+     * starts with: {@code '['}
+     *
      * @return whether this {@linkplain ClassDesc} describes an array type
      */
     default boolean isArray() {
@@ -210,6 +245,10 @@
     /**
      * Returns whether this {@linkplain ClassDesc} describes a primitive type.
      *
+     * @implSpec
+     * The default implementation returns {@code true} if the length of the
+     * descriptor is equal to 1
+     *
      * @return whether this {@linkplain ClassDesc} describes a primitive type
      */
     default boolean isPrimitive() {
@@ -219,6 +258,10 @@
     /**
      * Returns whether this {@linkplain ClassDesc} describes a class or interface type.
      *
+     * @implSpec
+     * The default implementation returns {@code true} if the descriptor starts with:
+     * {@code 'L'}
+     *
      * @return whether this {@linkplain ClassDesc} describes a class or interface type
      */
     default boolean isClassOrInterface() {
@@ -229,6 +272,12 @@
      * Returns the component type of this {@linkplain ClassDesc}, if it describes
      * an array type, or {@code null} otherwise.
      *
+     * @implSpec
+     * <p>The default implementation is equivalent to:
+     * <pre>{@code
+     *     return isArray() ? ClassDesc.ofDescriptor(descriptorString().substring(1)) : null;
+     * }</pre>
+     *
      * @return a {@linkplain ClassDesc} describing the component type, or {@code null}
      * if this descriptor does not describe an array type
      */
@@ -240,6 +289,16 @@
      * Returns the package name of this {@linkplain ClassDesc}, if it describes
      * a class or interface type.
      *
+     * @implSpec
+     * <p>The default implementation is equivalent to:
+     * <pre>{@code
+     *     if (!isClassOrInterface())
+     *         return "";
+     *     String className = internalToBinary(ConstantUtils.dropFirstAndLastChar(descriptorString()));
+     *     int index = className.lastIndexOf('.');
+     *     return (index == -1) ? "" : className.substring(0, index);
+     * }</pre>
+     *
      * @return the package name, or the empty string if the class is in the
      * default package, or this {@linkplain ClassDesc} does not describe a class or interface type
      */
@@ -254,6 +313,26 @@
     /**
      * Returns a human-readable name for the type described by this descriptor.
      *
+     * @implSpec
+     * <p>The default implementation is equivalent to:
+     * <pre>{@code
+     *     if (isPrimitive())
+     *         return Wrapper.forBasicType(descriptorString().charAt(0)).primitiveSimpleName();
+     *     else if (isClassOrInterface()) {
+     *         return descriptorString().substring(Math.max(1, descriptorString().lastIndexOf('/') + 1),
+     *                                             descriptorString().length() - 1);
+     *     }
+     *     else if (isArray()) {
+     *         int depth = ConstantUtils.arrayDepth(descriptorString());
+     *         ClassDesc c = this;
+     *         for (int i=0; i<depth; i++)
+     *             c = c.componentType();
+     *         return c.displayName() + "[]".repeat(depth);
+     *     }
+     *     else
+     *         throw new IllegalStateException(descriptorString());
+     * }</pre>
+     *
      * @return the human-readable name
      */
     default String displayName() {
@@ -275,7 +354,7 @@
     }
 
     /**
-     * Return a field type descriptor string for this type, as per JVMS 4.3.2
+     * Return a field type descriptor string for this type
      *
      * @return the descriptor string
      * @jvms 4.3.2 Field Descriptors
--- a/src/java.base/share/classes/java/lang/constant/ConstantDescs.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ConstantDescs.java	Wed Nov 21 15:24:03 2018 -0500
@@ -259,7 +259,7 @@
      * parameter types are {@code Lookup}, {@code String}, and {@code MethodType}.
      *
      * @param clazz the class declaring the method
-     * @param name the name of the method, as per JVMS 4.2.2
+     * @param name the unqualified name of the method
      * @param returnType the return type of the method
      * @param paramTypes the types of the static bootstrap arguments, if any
      * @return the {@link MethodHandleDesc}
@@ -280,7 +280,7 @@
      * {@code Lookup}, {@code String}, and {@code Class}.
      *
      * @param clazz the class declaring the method
-     * @param name the name of the method, as per JVMS 4.2.2
+     * @param name the unqualified name of the method
      * @param returnType the return type of the method
      * @param paramTypes the types of the static bootstrap arguments, if any
      * @return the {@link MethodHandleDesc}
--- a/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
@@ -52,8 +52,7 @@
      *
      * @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
-     * {@code CONSTRUCTOR}), as per JVMS 4.2.2
+     * @param name the unqualified name of the method (ignored if {@code kind} is {@code CONSTRUCTOR})
      * @param type the type of the method
      * @throws NullPointerException if any non-ignored argument is null
      * @throws IllegalArgumentException if {@code kind} describes a field accessor,
@@ -156,6 +155,14 @@
         }
     }
 
+    /**
+     * Returns {@code true} if the two direct method handle descriptors are equal.
+     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * @param o the {@code DirectMethodHandleDescImpl} to compare to this
+     *       {@code DirectMethodHandleDescImpl}
+     * @return {@code true} if the specified {@code DirectMethodHandleDescImpl} is
+     *      equals to this {@code DirectMethodHandleDescImpl}.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -167,6 +174,11 @@
                Objects.equals(type, desc.type);
     }
 
+    /**
+     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
+     *
+     * @see #equals
+     */
     @Override
     public int hashCode() {
         return Objects.hash(kind, owner, name, type);
--- a/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java	Wed Nov 21 15:24:03 2018 -0500
@@ -58,9 +58,8 @@
      *
      * @param bootstrapMethod a {@link DirectMethodHandleDescImpl} 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 invocationName The unqualified name that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}
      * @param invocationType a {@link MethodTypeDesc} describing the invocation
      *                       type that would appear in the {@code NameAndType}
      *                       operand of the {@code invokedynamic}
@@ -89,9 +88,8 @@
      *
      * @param bootstrapMethod a {@link DirectMethodHandleDescImpl} 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 invocationName The unqualified name that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}
      * @param invocationType a {@link MethodTypeDesc} describing the invocation
      *                       type that would appear in the {@code NameAndType}
      *                       operand of the {@code invokedynamic}
@@ -169,9 +167,8 @@
      * bootstrap and bootstrap arguments are the same as this one, but with the
      * specified invocationName and invocation invocationType
      *
-     * @param invocationName The name that would appear in the {@code NameAndType}
-     *                       operand of the {@code invokedynamic}, as per
-     *                       JVMS 4.2.2
+     * @param invocationName The unqualified name that would appear in the {@code NameAndType}
+     *                       operand of the {@code invokedynamic}
      * @param invocationType a {@link MethodTypeDesc} describing the invocation
      *                       type that would appear in the {@code NameAndType}
      *                       operand of the {@code invokedynamic}
@@ -241,6 +238,14 @@
         return (CallSite) bsm.invokeWithArguments(args);
     }
 
+    /**
+     * Returns {@code true} if the two dynamic call site descriptors are equal.
+     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * @param o the {@code DynamicCallSiteDesc} to compare to this
+     *       {@code DynamicCallSiteDesc}
+     * @return {@code true} if the specified {@code DynamicCallSiteDesc} is
+     *      equals to this {@code DynamicCallSiteDesc}.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -252,6 +257,11 @@
                Objects.equals(invocationType, specifier.invocationType);
     }
 
+    /**
+     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
+     *
+     * @see #equals
+     */
     @Override
     public int hashCode() {
         int result = Objects.hash(bootstrapMethod, invocationName, invocationType);
--- a/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java	Wed Nov 21 15:24:03 2018 -0500
@@ -78,9 +78,8 @@
      *
      * @param bootstrapMethod a {@link DirectMethodHandleDescImpl} 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 constantName The unqualified name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant
      * @param constantType a {@link DirectMethodHandleDescImpl} describing the type
      *                     that would appear in the {@code NameAndType} operand
      *                     of the {@code LDC} for this constant
@@ -124,9 +123,8 @@
      * @param <T> the type of the dynamic constant
      * @param bootstrapMethod a {@link DirectMethodHandleDesc} 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 constantName The unqualified name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant
      * @param constantType a {@link DirectMethodHandleDescImpl} describing the type
      *                     that would appear in the {@code NameAndType} operand
      *                     of the {@code LDC} for this constant
@@ -153,9 +151,8 @@
      * @param <T> the type of the dynamic constant
      * @param bootstrapMethod a {@link DirectMethodHandleDescImpl} 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 constantName The unqualified name that would appear in the {@code NameAndType}
+     *                     operand of the {@code LDC} for this constant
      * @param constantType a {@link ClassDesc} describing the type
      *                     that would appear in the {@code NameAndType} operand
      *                     of the {@code LDC} for this constant
@@ -349,6 +346,15 @@
 
     // @@@ To eventually support in canonicalization: DCR with BSM=MHR_METHODHANDLEDESC_ASTYPE becomes AsTypeMHDesc
 
+    /**
+     * Returns {@code true} if the two dynamic constant descriptors are equal.
+     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * @param o the {@code DynamicConstantDesc} to compare to this
+     *       {@code DynamicConstantDesc}
+     * @return {@code true} if the specified {@code DynamicConstantDesc} is
+     *      equals to this {@code DynamicConstantDesc}.
+     *
+     */
     @Override
     public final boolean equals(Object o) {
         if (this == o) return true;
@@ -360,6 +366,11 @@
                Objects.equals(constantType, desc.constantType);
     }
 
+    /**
+     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
+     *
+     * @see #equals
+     */
     @Override
     public final int hashCode() {
         int result = Objects.hash(bootstrapMethod, constantName, constantType);
--- a/src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java	Wed Nov 21 15:24:03 2018 -0500
@@ -61,8 +61,7 @@
      * @param kind The kind of method handle to be described
      * @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 name the unqualified name of the method or field (ignored if {@code kind} is {@code CONSTRUCTOR})
      * @param type a {@link MethodTypeDesc} describing the invocation type of
      *             the method handle
      * @return the {@linkplain MethodHandleDesc}
@@ -94,10 +93,9 @@
      * @param kind The kind of method handle to be described
      * @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 name the unqualified name of the method or field (ignored if {@code kind} is {@code CONSTRUCTOR})
      * @param descriptorString a method descriptor string for the invocation type
-     * of the method handle, as per JVMS 4.3.3
+     * of the method handle
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the non-ignored arguments are null
      * @jvms 4.2.2 Unqualified Names
@@ -126,8 +124,8 @@
      * @param kind The kind of method handle to be described
      * @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 name the unqualified name of the method or field (ignored if {@code kind} is
+     * {@code CONSTRUCTOR})
      * @param returnType a {@link ClassDesc} describing the return type of the
      *                   method handle
      * @param paramTypes {@link ClassDesc}s describing the parameter types of
@@ -152,7 +150,7 @@
      *             {@code SETTER}, {@code STATIC_GETTER}, or {@code STATIC_SETTER}
      * @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 fieldName the unqualified name 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
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java	Wed Nov 21 15:24:03 2018 -0500
@@ -51,7 +51,7 @@
     /**
      * Create a {@linkplain MethodTypeDesc} given a method descriptor string
      *
-     * @param descriptor a method descriptor string, as per JVMS 4.3.3
+     * @param descriptor a method descriptor string
      * @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
@@ -165,7 +165,7 @@
     MethodTypeDesc insertParameterTypes(int pos, ClassDesc... paramTypes);
 
     /**
-     * Return the method type descriptor string, as per JVMS 4.3.3.
+     * Return the method type descriptor string
      *
      * @return the method type descriptor string
      * @jvms 4.3.3 Method Descriptors
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
@@ -59,7 +59,7 @@
     /**
      * Create a {@linkplain MethodTypeDescImpl} given a method descriptor string.
      *
-     * @param descriptor the method descriptor string, as per JVMS 4.3.3
+     * @param descriptor the method descriptor string
      * @return a {@linkplain MethodTypeDescImpl} describing the desired method type
      * @throws IllegalArgumentException if the descriptor string is not a valid
      * method descriptor
@@ -137,6 +137,14 @@
         return MethodType.fromMethodDescriptorString(descriptorString(), lookup.lookupClass().getClassLoader());
     }
 
+    /**
+     * Returns {@code true} if the two method type descriptors are equal.
+     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * @param o the {@code MethodTypeDescImpl} to compare to this
+     *       {@code MethodTypeDescImpl}
+     * @return {@code true} if the specified {@code MethodTypeDescImpl} is
+     *      equals to this {@code MethodTypeDescImpl}.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -148,6 +156,11 @@
                && Arrays.equals(argTypes, constant.argTypes);
     }
 
+    /**
+     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
+     *
+     * @see #equals
+     */
     @Override
     public int hashCode() {
         int result = returnType.hashCode();
--- a/src/java.base/share/classes/java/lang/constant/PrimitiveClassDescImpl.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/PrimitiveClassDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
@@ -44,7 +44,7 @@
      * 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
+     * string corresponding to one of the nine base types
      * @throws IllegalArgumentException if the descriptor string does not
      * describe a valid primitive type
      * @jvms 4.3 Descriptors
--- a/src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
@@ -42,8 +42,7 @@
      * Create a {@linkplain ClassDesc} from a descriptor string for a class or
      * interface type
      *
-     * @param descriptor a field descriptor string for a class or interface type,
-     *                   as per JVMS 4.3.2
+     * @param descriptor a field descriptor string for a class or interface type
      * @throws IllegalArgumentException if the descriptor string is not a valid
      * field descriptor string, or does not describe a class or interface type
      * @jvms 4.3.2 Field Descriptors
@@ -80,6 +79,14 @@
         }
     }
 
+    /**
+     * Returns {@code true} if the two class descriptors are equal.
+     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * @param o the {@code ClassDesc} to compare to this
+     *       {@code ClassDesc}
+     * @return {@code true} if the specified {@code ClassDesc} is
+     *      equals to this {@code ClassDesc}.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -89,6 +96,11 @@
         return descriptor.equals(constant.descriptorString());
     }
 
+    /**
+     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
+     *
+     * @see #equals
+     */
     @Override
     public int hashCode() {
         return descriptor.hashCode();
--- a/src/java.base/share/classes/java/lang/invoke/MethodType.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java	Wed Nov 21 15:24:03 2018 -0500
@@ -1188,7 +1188,7 @@
     }
 
     /**
-     * Return a field type descriptor string for this type, as per JVMS 4.3.2
+     * Return a field type descriptor string for this type
      *
      * @return the descriptor string
      * @jvms 4.3.2 Field Descriptors
--- a/src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java	Wed Nov 21 15:24:03 2018 -0500
@@ -27,7 +27,7 @@
 import java.util.List;
 
 /**
- * An entity that has a field or method type descriptor, as per JVMS 4.3.2 or 4.3.3.
+ * An entity that has a field or method type descriptor
  * @jvms 4.3.2 Field Descriptors
  * @jvms 4.3.3 Method Descriptors
  *
@@ -42,7 +42,7 @@
 
 
     /**
-     * Represents a field type descriptor, as per JVMS 4.3.2.
+     * Represents a field type descriptor
      *
      * @param <F> the class implementing {@linkplain TypeDescriptor.OfField}
      * @jvms 4.3.2 Field Descriptors
@@ -79,7 +79,7 @@
 
 
     /**
-     * Represents a method type descriptor, as per JVMS 4.3.3
+     * Represents a method type descriptor
      *
      * @param <F> the type representing field type descriptors
      * @param <M> the class implementing {@linkplain TypeDescriptor.OfMethod}
--- a/src/java.base/share/classes/java/lang/invoke/VarHandle.java	Wed Nov 21 11:45:19 2018 -0500
+++ b/src/java.base/share/classes/java/lang/invoke/VarHandle.java	Wed Nov 21 15:24:03 2018 -0500
@@ -2174,8 +2174,7 @@
          * class.
          *
          * @param kind the kind of of the var handle
-         * @param name the name of the field, , as per JVMS 4.2.2, for field var
-         *             handles; otherwise ignored
+         * @param name the unqualified name of the field, 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
@@ -2195,7 +2194,7 @@
          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
          * for an instance field.
          *
-         * @param name the name of the field, as per JVMS 4.2.2
+         * @param name the unqualifed name of the field
          * @param declaringClass a {@link ClassDesc} describing the declaring class,
          *                       for field var handles
          * @param fieldType a {@link ClassDesc} describing the type of the field
@@ -2214,7 +2213,7 @@
          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
          * for a static field.
          *
-         * @param name the name of the field, as per JVMS 4.2.2
+         * @param name the unqualified name of the field
          * @param declaringClass a {@link ClassDesc} describing the declaring class,
          *                       for field var handles
          * @param fieldType a {@link ClassDesc} describing the type of the field