[PATCH] JDK-7033681 - Improve the documentation of Arrays.asList
Jonathan Gibbons
jonathan.gibbons at oracle.com
Wed Sep 19 22:43:43 UTC 2018
Stuart,
OK, I didn't know you already had that in mind.
-- Jon
On 09/19/2018 03:23 PM, Stuart Marks wrote:
> 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
>>
More information about the core-libs-dev
mailing list