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

[Jaikiran Pai]

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

-------------- next part --------------
# HG changeset patch
# User Jaikiran Pai <jaikiran.pai at gmail.com>
# Date 1535208403 -19800
#      Sat Aug 25 20:16:43 2018 +0530
# Node ID e4d5e71a20f7c80196f211f62440d3cccb69e8f3
# Parent  a716460217ed180972b568e28cf332e37e07a3ae
JDK-7033681 Improve the javadoc of Arrays#toList()

diff --git a/src/java.base/share/classes/java/util/Arrays.java b/src/java.base/share/classes/java/util/Arrays.java
--- a/src/java.base/share/classes/java/util/Arrays.java
+++ b/src/java.base/share/classes/java/util/Arrays.java
@@ -4288,21 +4288,33 @@
     // Misc
 
     /**
-     * Returns a fixed-size list backed by the specified array.  (Changes to
-     * the returned list "write through" to the array.)  This method acts
-     * as bridge between array-based and collection-based APIs, in
-     * combination with {@link Collection#toArray}.  The returned list is
-     * serializable and implements {@link RandomAccess}.
-     *
-     * <p>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>
+     * 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()
      */
     @SafeVarargs
     @SuppressWarnings("varargs")