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
diff -r cdffba164671 src/java.base/share/classes/java/util/Arrays.java --- a/src/java.base/share/classes/java/util/Arrays.java Mon Aug 20 10:04:00 2018 +0200 +++ b/src/java.base/share/classes/java/util/Arrays.java Mon Aug 20 17:53:21 2018 +0530 @@ -4288,18 +4288,35 @@ // 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 + * 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