JDK 16 RFR of JDK-8250660: Clarify that WildcardType and AnnotatedWildcardType bounds methods return one

[Joe Darcy]

Hello,

Please review the doc clarification below to address

     8250660: Clarify that WildcardType and AnnotatedWildcardType bounds 
methods return one

Thanks,

-Joe

diff -r b0553ba43ba1 
src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java
--- 
a/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java 
Fri Jul 31 11:35:25 2020 -0700
+++ 
b/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java 
Fri Jul 31 15:12:14 2020 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -30,6 +30,7 @@
   * wildcard type argument, whose upper or lower bounds may themselves 
represent
   * annotated uses of types.
   *
+ * @jls 4.5.1 Type Arguments of Parameterized Types
   * @since 1.8
   */
  public interface AnnotatedWildcardType extends AnnotatedType {
@@ -39,6 +40,9 @@
       * If no lower bound is explicitly declared, the lower bound is the
       * type of null. In this case, a zero length array is returned.
       *
+     * @apiNote In the current version of the Java Programming
+     * Language, a wildcard may have at most one lower bound.
+     *
       * @return the potentially annotated lower bounds of this wildcard 
type or
       * an empty array if no lower bound is explicitly declared.
       * @see WildcardType#getLowerBounds()
@@ -50,6 +54,9 @@
       * If no upper bound is explicitly declared, the upper bound is
       * unannotated {@code Object}
       *
+     * @apiNote In the current version of the Java Programming
+     * Language, a wildcard may have at most one upper bound.
+     *
       * @return the potentially annotated upper bounds of this wildcard 
type
       * @see WildcardType#getUpperBounds()
       */
diff -r b0553ba43ba1 
src/java.base/share/classes/java/lang/reflect/WildcardType.java
--- a/src/java.base/share/classes/java/lang/reflect/WildcardType.java 
Fri Jul 31 11:35:25 2020 -0700
+++ b/src/java.base/share/classes/java/lang/reflect/WildcardType.java 
Fri Jul 31 15:12:14 2020 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -29,6 +29,7 @@
   * WildcardType represents a wildcard type expression, such as
   * {@code ?}, {@code ? extends Number}, or {@code ? super Integer}.
   *
+ * @jls 4.5.1 Type Arguments of Parameterized Types
   * @since 1.5
   */
  public interface WildcardType extends Type {
@@ -45,6 +46,9 @@
       *  <li>Otherwise, B is resolved.
       * </ul>
       *
+     * @apiNote In the current version of the Java Programming
+     * Language, a wildcard may have at most one upper bound.
+     *
       * @return an array of Types representing the upper bound(s) of this
       *     type variable
       * @throws TypeNotPresentException if any of the
@@ -69,6 +73,9 @@
       *   <li>Otherwise, B is resolved.
       * </ul>
       *
+     * @apiNote In the current version of the Java Programming
+     * Language, a wildcard may have at most one lower bound.
+     *
       * @return an array of Types representing the lower bound(s) of this
       *     type variable
       * @throws TypeNotPresentException if any of the
@@ -78,6 +85,4 @@
       *     for any reason
       */
      Type[] getLowerBounds();
-    // one or many? Up to language spec; currently only one, but this API
-    // allows for generalization.
  }