[PATCH] JDK-7033681 - Improve the documentation of Arrays.asList

Jonathan Gibbons jonathan.gibbons at oracle.com
Wed Sep 19 22:43:43 UTC 2018


Stuart,

OK, I didn't know you already had that in mind.

-- Jon

On 09/19/2018 03:23 PM, Stuart Marks wrote:
> Hi Jon,
>
> Yes, definitely, given the scope of the current proposed changes, I 
> intend to file a CSR for this changeset on Jaikiran's behalf.
>
> s'marks
>
> On 9/19/18 10:42 AM, Jonathan Gibbons wrote:
>> Jaikiran,
>>
>> Referring back to the original email discussion, changes like this 
>> may require a
>> CSR to be filed.
>>
>>  From Stuart Marks:
>> http://mail.openjdk.java.net/pipermail/core-libs-dev/2018-August/054894.html 
>>
>>> Whether this requires a CSR depends on whether any normative text of 
>>> the
>>> specification is changed. A simple clarification ("API note") can be 
>>> added
>>> without a CSR. As the wording stands now, however, it seems like 
>>> there is a
>>> mixture of normative and informative statements in the text; these 
>>> should be
>>> teased apart and the informative statements placed into an API note. In
>>> addition, the normative text could probably be reworded to be more 
>>> clear. (See
>>> my comments in the bug.) Such changes would probably need a CSR, 
>>> even though
>>> they wouldn't actually change the intent of the specification.
>>
>> -- Jon
>>
>>
>> On 08/20/2018 05:26 AM, Jaikiran Pai wrote:
>>> Hello everyone,
>>>
>>> I'm requesting a review of a documentation change which was 
>>> discussed in
>>> a recent thread[1][2]. Here's an initial proposed draft, for a better
>>> documentation of Arrays.asList method:
>>>
>>>      /**
>>>       * Returns a fixed-size list backed by the specified array. The 
>>> passed
>>>       * array is held as a reference in the returned list. Any 
>>> subsequent
>>>       * changes made to the array contents will be visible in the 
>>> returned
>>>       * list. Similarly any changes that happen in the returned list 
>>> will
>>>       * also be visible in the array. The returned list is 
>>> serializable and
>>>       * implements {@link RandomAccess}.
>>>       *
>>>       * <p>The returned list can be changed only in certain ways. 
>>> Operations
>>>       * like {@code add}, {@code remove}, {@code clear} and other 
>>> such, that
>>>       * change the size of the list aren't allowed. Operations like
>>>       * {@code replaceAll}, {@code set}, that change the elements in 
>>> the list
>>>       * are permitted.
>>>       *
>>>       * <p>This method acts as bridge between array-based and
>>> collection-based
>>>       * APIs, in combination with {@link Collection#toArray}.
>>>       *
>>>       * @apiNote
>>>       * This method also provides a convenient way to create a 
>>> fixed-size
>>>       * list initialized to contain several elements:
>>>       * <pre>
>>>       *     List<String> stooges = Arrays.asList("Larry", "Moe",
>>> "Curly");
>>>       * </pre>
>>>       *
>>>       * <p>The returned list throws a {@link
>>> UnsupportedOperationException} for
>>>       * operations that aren't permitted. Certain implementations of 
>>> the
>>> returned
>>>       * list might choose to throw the exception only if the call to 
>>> such
>>> methods
>>>       * results in an actual change, whereas certain other
>>> implementations may
>>>       * always throw the exception when such methods are called.
>>>       *
>>>       * @param <T> the class of the objects in the array
>>>       * @param a the array by which the list will be backed
>>>       * @return a list view of the specified array
>>>       */
>>>      @SafeVarargs
>>>      @SuppressWarnings("varargs")
>>>      public static <T> List<T> asList(T... a)
>>>
>>>
>>> I've edited some of the existing documentation of that method, moved
>>> some existing parts into @apiNote and added additional parts both to 
>>> the
>>> spec as well as the @apiNote. For a complete reference of what's
>>> changed, I've also attached a patch of this change.
>>>
>>> P.S: Is there a specific (make) target that I can run to make sure
>>> changes like this one haven't caused any javadoc generation issues? I
>>> typically run just "make" and did it this time too, but I'm not sure it
>>> parses and generates the javadocs (couldn't find it in the generated
>>> exploded build image).
>>>
>>> [1]
>>> http://mail.openjdk.java.net/pipermail/core-libs-dev/2018-August/054894.html 
>>>
>>>
>>> [2] https://bugs.openjdk.java.net/browse/JDK-7033681
>>>
>>> -Jaikiran
>>



More information about the core-libs-dev mailing list