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

[David Holmes]

Hi Joe,

On 4/08/2020 2:24 am, Joe Darcy wrote:
> 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, 

Okay so we want to keep the API. :)

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

"to date" is just another form of "in the current version".

Sorry I find it hard to suggest suitable text when I don't think it 
necessary to say anything.

Best to let others endorse this one.

Cheers,
David
-----

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