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

[Jaikiran Pai]

Any other reviews? I'm not a committer, so I'll also need someone to
help sponsor this patch.

-Jaikiran


On 06/09/18 7:39 PM, Jaikiran Pai wrote:
> On 06/09/18 1:24 PM, Bernd Eckenfels wrote:
>> Yes you are right @apinote is aproperiate section (was confusing it with implnote).
>>
>> Still think a ‚literal specified list‘ is no longer a good (as in canonical) usecase for that method.
>>
>> I used it in the past often to get a List for using toString() on it, but I guess even for that case List.of can be used instead now.
>>
>> So @see List#of and let the reader figure out when to use them?
> That sounds good to me. I've now updated it to reflect this change and
> the javadoc now looks as below. I've also attached the new updated patch.
>
>     /**
>      * 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
>      * 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
>      * @see List#of()
>      */
>
>
>
> -Jaikiran
>