[PATCH] JDK-7033681 - Improve the documentation of Arrays.asList (original) (raw)

Jaikiran Pai jai.forums2013 at gmail.com
Wed Aug 29 04:36:42 UTC 2018

Anyone willing to help review the patch, please?

-Jaikiran

On 20/08/18 5:56 PM, 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}. * *

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. * *

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: * 

*     List stooges = Arrays.asList("Larry", "Moe",
"Curly");
* 
*
* 
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  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  List 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