# HG changeset patch
# User Jaikiran Pai <jaikiran.pai@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&lt;String&gt; 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")