changeset 53743:44346d4a2266 jep-334

minor documentation fixes after review
author vromero
date Wed, 05 Dec 2018 21:01:13 -0500
parents 67da852393b2
children 411969c7b5df
files src/java.base/share/classes/java/lang/Class.java src/java.base/share/classes/java/lang/Double.java src/java.base/share/classes/java/lang/Enum.java src/java.base/share/classes/java/lang/Float.java src/java.base/share/classes/java/lang/Integer.java src/java.base/share/classes/java/lang/Long.java src/java.base/share/classes/java/lang/String.java src/java.base/share/classes/java/lang/constant/ClassDesc.java src/java.base/share/classes/java/lang/constant/Constable.java src/java.base/share/classes/java/lang/constant/ConstantDesc.java src/java.base/share/classes/java/lang/constant/ConstantDescs.java src/java.base/share/classes/java/lang/constant/ConstantUtils.java src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.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/constant/package-info.java
diffstat 22 files changed, 88 insertions(+), 84 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/Class.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Class.java	Wed Dec 05 21:01:13 2018 -0500
@@ -160,7 +160,7 @@
                               GenericDeclaration,
                               Type,
                               AnnotatedElement,
-                                       TypeDescriptor.OfField<Class<?>>,
+                              TypeDescriptor.OfField<Class<?>>,
                               Constable {
     private static final int ANNOTATION= 0x00002000;
     private static final int ENUM      = 0x00004000;
@@ -4036,7 +4036,7 @@
     }
 
     /**
-     * Produce the type descriptor string for this class.
+     * Returns 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
@@ -4073,7 +4073,7 @@
     }
 
     /**
-     * Create a {@code Class} for an array type whose component type
+     * Returns a {@code Class} for an array type whose component type
      * is described by this {@linkplain Class}.
      *
      * @return a {@code Class} describing the array type
@@ -4085,7 +4085,7 @@
     }
 
     /**
-     * Return a nominal descriptor for this instance, if one can be
+     * Returns a nominal descriptor for this instance, if one can be
      * constructed, or an empty {@link Optional} if one cannot be.
      *
      * @return An {@link Optional} containing the resulting nominal descriptor,
--- a/src/java.base/share/classes/java/lang/Double.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Double.java	Wed Dec 05 21:01:13 2018 -0500
@@ -1089,7 +1089,7 @@
     }
 
     /**
-     * Resolve this instance as a {@link ConstantDesc}, the result of which is
+     * Resolves this instance as a {@link ConstantDesc}, the result of which is
      * the instance itself.
      *
      * @param lookup ignored
--- a/src/java.base/share/classes/java/lang/Enum.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Enum.java	Wed Dec 05 21:01:13 2018 -0500
@@ -212,7 +212,7 @@
     }
 
     /**
-     * Return an enum descriptor {@code EnumDesc} for this instance, if one can be
+     * Returns an enum descriptor {@code EnumDesc} for this instance, if one can be
      * constructed, or an empty {@link Optional} if one cannot be.
      *
      * @return An {@link Optional} containing the resulting nominal descriptor,
@@ -294,7 +294,7 @@
             extends DynamicConstantDesc<E> {
 
         /**
-         * Construct a nominal descriptor for the specified {@code enum} class and name.
+         * Constructs a nominal descriptor for the specified {@code enum} class and name.
          *
          * @param constantType a {@link ClassDesc} describing the {@code enum} class
          * @param constantName the unqualified name of the enum constant
@@ -306,7 +306,7 @@
         }
 
         /**
-         * Return a nominal descriptor for the specified {@code enum} class and name
+         * Returns a nominal descriptor for the specified {@code enum} class and name
          *
          * @param <E> the type of the enum constant
          * @param enumClass a {@link ClassDesc} describing the {@code enum} class
--- a/src/java.base/share/classes/java/lang/Float.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Float.java	Wed Dec 05 21:01:13 2018 -0500
@@ -1001,7 +1001,7 @@
     }
 
     /**
-     * Resolve this instance as a {@link ConstantDesc}, the result of which is
+     * Resolves this instance as a {@link ConstantDesc}, the result of which is
      * the instance itself.
      *
      * @param lookup ignored
--- a/src/java.base/share/classes/java/lang/Integer.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Integer.java	Wed Dec 05 21:01:13 2018 -0500
@@ -1850,7 +1850,7 @@
     }
 
     /**
-     * Resolve this instance as a {@link ConstantDesc}, the result of which is
+     * Resolves this instance as a {@link ConstantDesc}, the result of which is
      * the instance itself.
      *
      * @param lookup ignored
--- a/src/java.base/share/classes/java/lang/Long.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/Long.java	Wed Dec 05 21:01:13 2018 -0500
@@ -1979,7 +1979,7 @@
     }
 
     /**
-     * Resolve this instance as a {@link ConstantDesc}, the result of which is
+     * Resolves this instance as a {@link ConstantDesc}, the result of which is
      * the instance itself.
      *
      * @param lookup ignored
--- a/src/java.base/share/classes/java/lang/String.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/String.java	Wed Dec 05 21:01:13 2018 -0500
@@ -3557,7 +3557,7 @@
     }
 
     /**
-     * Resolve this instance as a {@link ConstantDesc}, the result of which is
+     * Resolves this instance as a {@link ConstantDesc}, the result of which is
      * the instance itself.
      *
      * @param lookup ignored
--- a/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -63,7 +63,7 @@
                 TypeDescriptor.OfField<ClassDesc> {
 
     /**
-     * Create a {@linkplain ClassDesc} for a class or interface type,
+     * Returns a {@linkplain ClassDesc} for a class or interface type,
      * given the name of the class or interface, such as {@code "java.lang.String"}.
      * (To create a descriptor for an array type, either use {@link #ofDescriptor(String)}
      * or {@link #arrayType()}; to create a descriptor for a primitive type, use
@@ -82,7 +82,7 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} for a class or interface type,
+     * Returns a {@linkplain ClassDesc} for a class or interface type,
      * given a package name and the unqualified (simple) name for the
      * class or interface.
      *
@@ -105,7 +105,7 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} given a descriptor string for a class,
+     * Returns a {@linkplain ClassDesc} given a descriptor string for a class,
      * interface, array, or primitive type.
      *
      * @apiNote
@@ -135,7 +135,7 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} for an array type whose component type
+     * Returns a {@linkplain ClassDesc} for an array type whose component type
      * is described by this {@linkplain ClassDesc}.
      *
      * @return a {@linkplain ClassDesc} describing the array type
@@ -145,7 +145,7 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} for an array type of the specified rank,
+     * Returns 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
@@ -159,7 +159,7 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} for an inner class of the class or
+     * Returns 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
@@ -167,6 +167,7 @@
      * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalStateException if this {@linkplain ClassDesc} does not
      * describe a class or interface type
+     * @throws IllegalArgumentException if the inner class name is invalid
      */
     default ClassDesc inner(String innerName) {
         validateMemberName(innerName);
@@ -176,7 +177,7 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} for an inner class of the class or
+     * Returns a {@linkplain ClassDesc} for an inner class of the class or
      * interface type described by this {@linkplain ClassDesc}.
      *
      * @param firstInnerName the unqualified name of the first level of inner class
@@ -186,6 +187,7 @@
      * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalStateException if this {@linkplain ClassDesc} does not
      * describe a class or interface type
+     * @throws IllegalArgumentException if the inner class name is invalid
      */
     default ClassDesc inner(String firstInnerName, String... moreInnerNames) {
         if (!isClassOrInterface())
@@ -278,7 +280,7 @@
     }
 
     /**
-     * Return a field type descriptor string for this type
+     * Returns 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/Constable.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/Constable.java	Wed Dec 05 21:01:13 2018 -0500
@@ -65,8 +65,8 @@
  */
 public interface Constable {
     /**
-     * Return a nominal descriptor for this instance, if one can be
-     * constructed, or an empty {@link Optional} if one cannot be.
+     * Returns a 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.
--- a/src/java.base/share/classes/java/lang/constant/ConstantDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ConstantDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -37,7 +37,7 @@
  * 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
+ * of a classfile, must be interpreted with respect to a particular class
  * loader, which is not part of the nominal descriptor.
  *
  * <p>Static constants that are expressible natively in the constant pool ({@link String},
@@ -86,7 +86,7 @@
  */
 public interface ConstantDesc {
     /**
-     * Resolve this descriptor reflectively, emulating the resolution behavior
+     * Resolves this descriptor reflectively, emulating the resolution behavior
      * of JVMS 5.4.3 and the access control behavior of JVMS 5.4.4.  The resolution
      * and access control context is provided by the {@link MethodHandles.Lookup}
      * parameter.  No caching of the resulting value is performed.
--- a/src/java.base/share/classes/java/lang/constant/ConstantDescs.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ConstantDescs.java	Wed Dec 05 21:01:13 2018 -0500
@@ -255,7 +255,7 @@
             = MethodHandleDesc.ofMethod(Kind.VIRTUAL, CD_MethodHandle, "asType",
                                         MethodTypeDesc.of(CD_MethodHandle, CD_MethodType));
     /**
-     * Return a {@link MethodHandleDesc} corresponding to a bootstrap method for
+     * Returns a {@link MethodHandleDesc} corresponding to a bootstrap method for
      * an {@code invokedynamic} callsite, which is a static method whose leading
      * parameter types are {@code Lookup}, {@code String}, and {@code MethodType}.
      *
@@ -276,7 +276,7 @@
     }
 
     /**
-     * Return a {@link MethodHandleDesc} corresponding to a bootstrap method for a
+     * Returns a {@link MethodHandleDesc} corresponding to a bootstrap method for a
      * dynamic constant, which is a static method whose leading arguments are
      * {@code Lookup}, {@code String}, and {@code Class}.
      *
--- a/src/java.base/share/classes/java/lang/constant/ConstantUtils.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ConstantUtils.java	Wed Dec 05 21:01:13 2018 -0500
@@ -99,7 +99,7 @@
     }
 
     /**
-     * Parse a method descriptor string, and return a list of field descriptor
+     * Parses a method descriptor string, and return a list of field descriptor
      * strings, return type first, then parameter types
      *
      * @param descriptor the descriptor string
@@ -133,7 +133,7 @@
     }
 
     /**
-     * Validate that the characters at [start, end) within the provided string
+     * Validates that the characters at [start, end) within the provided string
      * describe a valid field type descriptor.
      *
      * @param str the descriptor string
--- a/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -56,6 +56,8 @@
 public interface DirectMethodHandleDesc extends MethodHandleDesc {
     /**
      * Kinds of method handles that can be described with {@linkplain DirectMethodHandleDesc}.
+     *
+     * @since 12
      */
     enum Kind {
         /** A method handle for a method invoked as with {@code invokestatic} */
@@ -96,7 +98,7 @@
         Kind(int refKind, boolean isInterface) { this.refKind = refKind; this.isInterface = isInterface; }
 
         /**
-         * Find the enumeration member with the given {@code refKind} field.
+         * Returns the enumeration member with the given {@code refKind} field.
          * Behaves as if {@code valueOf(refKind, false)}.  As a special case,
          * if {@code refKind} is {@code REF_invokeInterface} (9) then the
          * {@code isInterface} field will be true.
@@ -110,7 +112,7 @@
         }
 
         /**
-         * Find the enumeration member with the given the {@code refKind} and
+         * Returns the enumeration member with the given the {@code refKind} and
          * {@code isInterface} arguments.
          * For most values of {@code refKind} there is an exact match regardless of the value of {@code isInterface}.
          * These are:
@@ -208,7 +210,7 @@
     }
 
     /**
-     * Return the {@code kind} of the method handle described by this nominal
+     * Returns the {@code kind} of the method handle described by this nominal
      * descriptor.
      *
      * @return the {@link Kind}
@@ -216,7 +218,7 @@
     Kind kind();
 
     /**
-     * Return the {@code refKind} of the method handle described by this nominal
+     * Returns the {@code refKind} of the method handle described by this nominal
      * reference, as defined by {@link MethodHandleInfo}.
      *
      * @return the reference kind
@@ -231,7 +233,7 @@
     boolean isOwnerInterface();
 
     /**
-     * Return a {@link ClassDesc} describing the class declaring the
+     * Returns a {@link ClassDesc} describing the class declaring the
      * method or field described by this nominal descriptor.
      *
      * @return the class declaring the method or field
@@ -239,7 +241,7 @@
     ClassDesc owner();
 
     /**
-     * Return the name of the method or field described by this nominal descriptor.
+     * Returns the name of the method or field described by this nominal descriptor.
      * For constructors, returns the reserved name {@code "<init>"}.
      *
      * @return the name of the method or field
@@ -247,7 +249,7 @@
     String methodName();
 
     /**
-     * Return the lookup descriptor of the method handle described by this descriptor,
+     * Returns the lookup descriptor of the method handle described by this descriptor,
      * after adjusting for the invocation mode.  This will correspond to either
      * a method type descriptor string (for methods and constructors), or a field
      * descriptor string (for field access method handles).  The lookup descriptor
--- a/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java	Wed Dec 05 21:01:13 2018 -0500
@@ -48,7 +48,7 @@
     private final MethodTypeDesc invocationType;
 
     /**
-     * Construct a {@linkplain DirectMethodHandleDescImpl} for a method or field
+     * Constructs a {@linkplain DirectMethodHandleDescImpl} for a method or field
      * from a kind, owner, name, and type
      *
      * @param kind the kind of the method handle
--- a/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -54,7 +54,7 @@
     private final MethodTypeDesc invocationType;
 
     /**
-     * Create a nominal descriptor for an {@code invokedynamic} call site.
+     * Creates a nominal descriptor for an {@code invokedynamic} call site.
      *
      * @param bootstrapMethod a {@link DirectMethodHandleDesc} describing the
      *                        bootstrap method for the {@code invokedynamic}
@@ -84,7 +84,7 @@
     }
 
     /**
-     * Create a nominal descriptor for an {@code invokedynamic} call site.
+     * Creates a nominal descriptor for an {@code invokedynamic} call site.
      *
      * @param bootstrapMethod a {@link DirectMethodHandleDesc} describing the
      *                        bootstrap method for the {@code invokedynamic}
@@ -110,7 +110,7 @@
     }
 
     /**
-     * Create a nominal descriptor for an {@code invokedynamic} call site whose
+     * Creates 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}
@@ -120,6 +120,8 @@
      * 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
      */
     public static DynamicCallSiteDesc of(DirectMethodHandleDesc bootstrapMethod,
                                          String invocationName,
@@ -128,7 +130,7 @@
     }
 
     /**
-     * Create a nominal descriptor for an {@code invokedynamic} call site whose
+     * Creates 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}.
      *
@@ -139,8 +141,6 @@
      *                       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
      */
     public static DynamicCallSiteDesc of(DirectMethodHandleDesc bootstrapMethod,
                                          MethodTypeDesc invocationType) {
@@ -148,7 +148,7 @@
     }
 
     /**
-     * Return a nominal descriptor for an {@code invokedynamic} call site whose
+     * Returns a nominal descriptor for an {@code invokedynamic} call site whose
      * bootstrap method, name, and invocation type are the same as this one, but
      * with the specified bootstrap arguments.
      *
@@ -163,7 +163,7 @@
     }
 
     /**
-     * Return a nominal descriptor for an {@code invokedynamic} call site whose
+     * Returns a nominal descriptor for an {@code invokedynamic} call site whose
      * bootstrap and bootstrap arguments are the same as this one, but with the
      * specified invocationName and invocation invocationType
      *
--- a/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -74,7 +74,7 @@
     );
 
     /**
-     * Create a nominal descriptor for a dynamic constant.
+     * Creates a nominal descriptor for a dynamic constant.
      *
      * @param bootstrapMethod a {@link DirectMethodHandleDesc} describing the
      *                        bootstrap method for the constant
@@ -105,11 +105,11 @@
     }
 
     /**
-     * Return a nominal descriptor for a dynamic constant, transforming it into
+     * Returns 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
+     * <p>Classes whose {@link Constable#describeConstable()} method produce
      * a {@linkplain DynamicConstantDesc} with a well-known bootstrap including
      * {@link Class} (for instances describing primitive types), {@link Enum},
      * and {@link VarHandle}.
@@ -146,7 +146,7 @@
     }
 
     /**
-     * Return a nominal descriptor for a dynamic constant.
+     * Returns a nominal descriptor for a dynamic constant.
      *
      * @param <T> the type of the dynamic constant
      * @param bootstrapMethod a {@link DirectMethodHandleDesc} describing the
@@ -174,7 +174,7 @@
     }
 
     /**
-     * Return a nominal descriptor for a dynamic constant whose name parameter
+     * Returns a nominal descriptor for a dynamic constant whose name parameter
      * is {@link ConstantDescs#DEFAULT_NAME}, and whose type parameter is always
      * the same as the bootstrap method return type.
      *
@@ -194,7 +194,7 @@
     }
 
     /**
-     * Return a nominal descriptor for a dynamic constant whose bootstrap has
+     * Returns a nominal descriptor for a dynamic constant whose bootstrap has
      * no static arguments, whose name parameter is {@link ConstantDescs#DEFAULT_NAME},
      * and whose type parameter is always the same as the bootstrap method return type.
      *
@@ -210,7 +210,7 @@
 
     /**
      * Returns the name that would appear in the {@code NameAndType} operand
-     * of the {@code LDC} for this constant
+     * of the {@code LDC} for this constant.
      *
      * @return the constant name
      */
@@ -230,7 +230,7 @@
 
     /**
      * Returns a {@link MethodHandleDesc} describing the bootstrap method for
-     * this constant
+     * this constant.
      *
      * @return the bootstrap method
      */
@@ -239,7 +239,7 @@
     }
 
     /**
-     * Returns the bootstrap arguments for this constant
+     * Returns the bootstrap arguments for this constant.
      *
      * @return the bootstrap arguments
      */
@@ -248,7 +248,7 @@
     }
 
     /**
-     * Returns the bootstrap arguments for this constant as an immutable {@link List}
+     * Returns the bootstrap arguments for this constant as an immutable {@link List}.
      *
      * @return a {@link List} of the bootstrap arguments
      */
--- a/src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -46,7 +46,7 @@
         extends ConstantDesc {
 
     /**
-     * Create a {@linkplain MethodHandleDesc} corresponding to an invocation of a
+     * Creates a {@linkplain MethodHandleDesc} corresponding to an invocation of a
      * declared method, invocation of a constructor, or access to a field.
      *
      * <p>The lookup descriptor string has the same format as for the various
@@ -91,7 +91,7 @@
     }
 
     /**
-     * Create a {@linkplain MethodHandleDesc} corresponding to an invocation of a
+     * Creates a {@linkplain MethodHandleDesc} corresponding to an invocation of a
      * declared method or constructor.
      *
      * <p>The lookup descriptor string has the same format as for the lookup
@@ -139,7 +139,7 @@
     }
 
     /**
-     * Create a {@linkplain MethodHandleDesc} corresponding to a method handle
+     * Creates a {@linkplain MethodHandleDesc} corresponding to a method handle
      * that accesses a field.
      *
      * @param kind the kind of the method handle to be described; must be one of {@code GETTER},
@@ -150,7 +150,7 @@
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the arguments are null
      * @throws IllegalArgumentException if the {@code kind} is not one of the
-     * valid values
+     * valid values or if the field name is not valid
      * @jvms 4.2.2 Unqualified Names
      */
     static DirectMethodHandleDesc ofField(DirectMethodHandleDesc.Kind kind,
@@ -170,7 +170,7 @@
     }
 
     /**
-     * Return a {@linkplain MethodHandleDesc} corresponding to invocation of a constructor
+     * Returns a {@linkplain MethodHandleDesc} corresponding to invocation of a constructor
      *
      * @param owner a {@link ClassDesc} describing the class containing the
      *              constructor
@@ -186,7 +186,7 @@
     }
 
     /**
-     * Return a {@linkplain MethodHandleDesc} that describes this method handle
+     * Returns a {@linkplain MethodHandleDesc} that describes this method handle
      * adapted to a different type, as if by {@link MethodHandle#asType(MethodType)}.
      *
      * @param type a {@link MethodHandleDesc} describing the new method type
@@ -197,7 +197,7 @@
     }
 
     /**
-     * Return a {@link MethodTypeDesc} describing the invocation type of the
+     * Returns a {@link MethodTypeDesc} describing the invocation type of the
      * method handle described by this nominal descriptor.  The invocation type
      * describes the full set of stack values that are consumed by the invocation
      * (including the receiver, if any).
@@ -207,7 +207,7 @@
     MethodTypeDesc invocationType();
 
     /**
-     * Compare the specified object with this descriptor for equality.  Returns
+     * Compares the specified object with this descriptor for equality.  Returns
      * {@code true} if and only if the specified object is also a
      * {@linkplain MethodHandleDesc}, and both encode the same nominal description
      * of a method handle.
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java	Wed Dec 05 21:01:13 2018 -0500
@@ -45,7 +45,7 @@
         extends ConstantDesc,
                 TypeDescriptor.OfMethod<ClassDesc, MethodTypeDesc> {
     /**
-     * Create a {@linkplain MethodTypeDesc} given a method descriptor string
+     * Creates a {@linkplain MethodTypeDesc} given a method descriptor string.
      *
      * @param descriptor a method descriptor string
      * @return a {@linkplain MethodTypeDesc} describing the desired method type
@@ -72,22 +72,22 @@
     }
 
     /**
-     * Get the return type of the method type described by this {@linkplain MethodTypeDesc}
+     * Gets the return type of the method type described by this {@linkplain MethodTypeDesc}.
      *
      * @return a {@link ClassDesc} describing the return type of the method type
      */
     ClassDesc returnType();
 
     /**
-     * Get the number of parameters of the method type described by
-     * this {@linkplain MethodTypeDesc}
+     * Returns the number of parameters of the method type described by
+     * this {@linkplain MethodTypeDesc}.
      * @return the number of parameters
      */
     int parameterCount();
 
     /**
-     * Get the parameter type of the {@code index}'th parameter of the method type
-     * described by this {@linkplain MethodTypeDesc}
+     * Returns the parameter type of the {@code index}'th parameter of the method type
+     * described by this {@linkplain MethodTypeDesc}.
      *
      * @param index the index of the parameter to retrieve
      * @return a {@link ClassDesc} describing the desired parameter type
@@ -97,21 +97,21 @@
     ClassDesc parameterType(int index);
 
     /**
-     * Get the parameter types as an immutable {@link List}.
+     * Returns the parameter types as an immutable {@link List}.
      *
      * @return a {@link List} of {@link ClassDesc} describing the parameter types
      */
     List<ClassDesc> parameterList();
 
     /**
-     * Get the parameter types as an array.
+     * Returns the parameter types as an array.
      *
      * @return an array of {@link ClassDesc} describing the parameter types
      */
     ClassDesc[] parameterArray();
 
     /**
-     * Return a {@linkplain MethodTypeDesc} that is identical to
+     * Returns a {@linkplain MethodTypeDesc} that is identical to
      * this one, except with the specified return type.
      *
      * @param returnType a {@link ClassDesc} describing the new return type
@@ -121,7 +121,7 @@
     MethodTypeDesc changeReturnType(ClassDesc returnType);
 
     /**
-     * Return a {@linkplain MethodTypeDesc} that is identical to this one,
+     * Returns a {@linkplain MethodTypeDesc} that is identical to this one,
      * except that a single parameter type has been changed to the specified type.
      *
      * @param index the index of the parameter to change
@@ -134,7 +134,7 @@
     MethodTypeDesc changeParameterType(int index, ClassDesc paramType);
 
     /**
-     * Return a {@linkplain MethodTypeDesc} that is identical to this one,
+     * Returns a {@linkplain MethodTypeDesc} that is identical to this one,
      * except that a range of parameter types have been removed.
      *
      * @param start the index of the first parameter to remove
@@ -147,7 +147,7 @@
     MethodTypeDesc dropParameterTypes(int start, int end);
 
     /**
-     * Return a {@linkplain MethodTypeDesc} that is identical to this one,
+     * Returns a {@linkplain MethodTypeDesc} that is identical to this one,
      * except that a range of additional parameter types have been inserted.
      *
      * @param pos the index at which to insert the first inserted parameter
@@ -161,7 +161,7 @@
     MethodTypeDesc insertParameterTypes(int pos, ClassDesc... paramTypes);
 
     /**
-     * Return the method type descriptor string
+     * Returns the method type descriptor string.
      *
      * @return the method type descriptor string
      * @jvms 4.3.3 Method Descriptors
@@ -175,8 +175,8 @@
     }
 
     /**
-     * Return a human-readable descriptor for this method type, using the
-     * canonical names for parameter and return types
+     * Returns 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
      */
@@ -189,7 +189,7 @@
     }
 
     /**
-     * Compare the specified object with this descriptor for equality.  Returns
+     * Compares the specified object with this descriptor for equality.  Returns
      * {@code true} if and only if the specified object is also a
      * {@linkplain MethodTypeDesc} both have the same arity, their return types
      * are equal, and each pair of corresponding parameter types are equal.
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java	Wed Dec 05 21:01:13 2018 -0500
@@ -41,7 +41,7 @@
     private final ClassDesc[] argTypes;
 
     /**
-     * Construct a {@linkplain MethodTypeDesc} with the specified return type
+     * Constructs a {@linkplain MethodTypeDesc} with the specified return type
      * and parameter types
      *
      * @param returnType a {@link ClassDesc} describing the return type
@@ -57,7 +57,7 @@
     }
 
     /**
-     * Create a {@linkplain MethodTypeDescImpl} given a method descriptor string.
+     * Creates a {@linkplain MethodTypeDescImpl} given a method descriptor string.
      *
      * @param descriptor the method descriptor string
      * @return a {@linkplain MethodTypeDescImpl} describing the desired method type
--- a/src/java.base/share/classes/java/lang/constant/PrimitiveClassDescImpl.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/PrimitiveClassDescImpl.java	Wed Dec 05 21:01:13 2018 -0500
@@ -40,7 +40,7 @@
     private final String descriptor;
 
     /**
-     * Create a {@linkplain ClassDesc} given a descriptor string for a primitive
+     * Creates a {@linkplain ClassDesc} given a descriptor string for a primitive
      * type.
      *
      * @param descriptor the descriptor string, which must be a one-character
--- a/src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java	Wed Dec 05 21:01:13 2018 -0500
@@ -39,7 +39,7 @@
     private final String descriptor;
 
     /**
-     * Create a {@linkplain ClassDesc} from a descriptor string for a class or
+     * Creates 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
--- a/src/java.base/share/classes/java/lang/constant/package-info.java	Wed Dec 05 12:52:08 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/package-info.java	Wed Dec 05 21:01:13 2018 -0500
@@ -54,14 +54,14 @@
  * 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.constant.ConstantDesc} describe various kinds
+ * <p>The subtypes of {@link java.lang.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.constant.ConstantDesc}:
  * {@link java.lang.constant.ClassDesc}, {@link java.lang.constant.MethodTypeDesc},
  * {@link java.lang.constant.DirectMethodHandleDesc}, {@link java.lang.String},
  * {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Float},
  * {@link java.lang.Double}, and {@link java.lang.constant.DynamicConstantDesc}.  These classes
- * provides type-specific accessor methods to extract the nominal information for
+ * provide type-specific accessor methods to extract the nominal information for
  * that kind of constant.  When a bytecode-writing API encounters a {@link java.lang.constant.ConstantDesc},
  * it should examine it to see which of these types it is, cast it, extract
  * its nominal information, and generate the corresponding entry to the constant pool.