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

[Jonathan Gibbons]

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