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.
>>   }
>>