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

[Stuart Marks]

Hi Jon,

Yes, definitely, given the scope of the current proposed changes, I intend to 
file a CSR for this changeset on Jaikiran's behalf.

s'marks

On 9/19/18 10:42 AM, Jonathan Gibbons wrote:
> 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
>