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

[Joe Darcy]

Hi David,

To provide a bit more context, the API was consciously designed to be 
future-proofed against the possibility of Java supporting multiple 
bounds here (JDK-4891872). As of yet, that change has not come to pass, 
and as you note may never come to pass. So besides in addition to the 
links into the JLS, I think it is reasonable to include an API note 
acknowledging the situation. How about:

    This method supports the existence of multiple bounds, but to date, 
a wildcard may have at most one upper/lower bound.

-Joe


On 8/2/2020 7:22 PM, David Holmes wrote:
Hi Joe,

I was under the impression that using phrases like "the current 
version of" were superfluous as all such documentation implicitly 
refers to the current version, unless explicitly stated otherwise.

Personally I'm not sure this clarification really makes a difference 
to anything as the main source of confusion with this API is why it 
states "bounds" rather than "bound" and thus returns an array. By 
adding this clarification you will require a future update if the 
language allows multiple bounds, forcing the docs to carry around 
historical data "prior to Java N only a single bound were allowed but 
since then multiple bounds ...". This seems unnecessary clutter to me. 
Given the ship has sailed on the shape of this API the developer must 
simply embrace it and always process the return value in a loop 
without assuming any knowledge of how many bounds may actually exist.

I think the reference to the JLS section suffices to instruct the 
developer on where to find out how many bounds to expect, whatever 
that may be in their current version of the JLS.

If we think we will never support multiple bounds then these methods 
should be deprecated (for removal) and replaced by a singular 
counterpart that returns a single Type rather than a Type[].

Cheers,
David
-----

On 1/08/2020 8:12 am, Joe Darcy wrote:
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.
  }