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

[Jaikiran Pai]

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
-------------- next part --------------
diff -r cdffba164671 src/java.base/share/classes/java/util/Arrays.java
--- a/src/java.base/share/classes/java/util/Arrays.java	Mon Aug 20 10:04:00 2018 +0200
+++ b/src/java.base/share/classes/java/util/Arrays.java	Mon Aug 20 17:53:21 2018 +0530
@@ -4288,18 +4288,35 @@
     // 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
+     * 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