8278953: Clarify Class.getDeclaredConstructor specification

Reviewed-by: mchung, alanb

src/java.base/share/classes/java/lang/Class.java

@@ -2080,6 +2080,7 @@ public Method[] getMethods() throws SecurityException {
      *         s.checkPackageAccess()} denies access to the package
      *         of this class.
      *
+     * @see #getDeclaredConstructors()
      * @since 1.1
      */
     @CallerSensitive
@@ -2279,7 +2280,9 @@ public Method getMethod(String name, Class<?>... parameterTypes)
      * @param parameterTypes the parameter array
      * @return the {@code Constructor} object of the public constructor that
      *         matches the specified {@code parameterTypes}
-     * @throws NoSuchMethodException if a matching method is not found.
+     * @throws NoSuchMethodException if a matching constructor is not found,
+     *         including when this {@code Class} object represents
+     *         an interface, a primitive type, an array class, or void.
      * @throws SecurityException
      *         If a security manager, <i>s</i>, is present and
      *         the caller's class loader is not the same as or an
@@ -2288,6 +2291,7 @@ public Method getMethod(String name, Class<?>... parameterTypes)
      *         s.checkPackageAccess()} denies access to the package
      *         of this class.
      *
+     * @see #getDeclaredConstructor(Class<?>[])
      * @since 1.1
      */
     @CallerSensitive
@@ -2536,21 +2540,20 @@ public Method[] getDeclaredMethods() throws SecurityException {
         return copyMethods(privateGetDeclaredMethods(false));
     }
 
-
     /**
      * Returns an array of {@code Constructor} objects reflecting all the
-     * constructors declared by the class represented by this
+     * constructors implicitly or explicitly declared by the class represented by this
      * {@code Class} object. These are public, protected, default
      * (package) access, and private constructors.  The elements in the array
      * returned are not sorted and are not in any particular order.  If the
-     * class has a default constructor, it is included in the returned array.
+     * class has a default constructor (JLS {@jls 8.8.9}), it is included in the returned array.
+     * If a record class has a canonical constructor (JLS {@jls
+     * 8.10.4.1}, {@jls 8.10.4.2}), it is included in the returned array.
+     *
      * This method returns an array of length 0 if this {@code Class}
      * object represents an interface, a primitive type, an array class, or
      * void.
      *
-     * <p> See <cite>The Java Language Specification</cite>,
-     * section {@jls 8.2}.
-     *
      * @return  the array of {@code Constructor} objects representing all the
      *          declared constructors of this class
      * @throws  SecurityException
@@ -2575,6 +2578,7 @@ public Method[] getDeclaredMethods() throws SecurityException {
      *          </ul>
      *
      * @since 1.1
+     * @see #getConstructors()
      * @jls 8.8 Constructor Declarations
      */
     @CallerSensitive
@@ -2736,7 +2740,7 @@ List<Method> getDeclaredPublicMethods(String name, Class<?>... parameterTypes) {
 
     /**
      * Returns a {@code Constructor} object that reflects the specified
-     * constructor of the class or interface represented by this
+     * constructor of the class represented by this
      * {@code Class} object.  The {@code parameterTypes} parameter is
      * an array of {@code Class} objects that identify the constructor's
      * formal parameter types, in declared order.
@@ -2748,7 +2752,9 @@ List<Method> getDeclaredPublicMethods(String name, Class<?>... parameterTypes) {
      * @param parameterTypes the parameter array
      * @return  The {@code Constructor} object for the constructor with the
      *          specified parameter list
-     * @throws  NoSuchMethodException if a matching method is not found.
+     * @throws  NoSuchMethodException if a matching constructor is not found,
+     *          including when this {@code Class} object represents
+     *          an interface, a primitive type, an array class, or void.
      * @throws  SecurityException
      *          If a security manager, <i>s</i>, is present and any of the
      *          following conditions is met:
@@ -2770,6 +2776,7 @@ List<Method> getDeclaredPublicMethods(String name, Class<?>... parameterTypes) {
      *
      *          </ul>
      *
+     * @see #getConstructor(Class<?>[])
      * @since 1.1
      */
     @CallerSensitive