Hello, Not an Reviewer But just wanted to give a short Feedback: I like the new Version it is really helpful.
However I wonder if the usage example should be outside of the apinote. Given the existence of List.of() I wonder if you either mention it as a alternative to the example (with slightly different semantic) or just remove the sample completely? „Similiar to List.of() which constructs an unmodifiable List from given elements Arrays.asList() can be used to construct a List from a fixed size of Elements. Both constructs won’t allow structural changes to the resulting List, however when constructed with asList() the content could be modified.“ But I must honestly say this would encourage a usage which is a bit questionable in many cases? Gruss Bernd -- http://bernd.eckenfels.net ________________________________ Von: -997621984m Auftrag von Gesendet: Mittwoch, August 29, 2018 9:07 AM An: core-libs-dev@openjdk.java.net Betreff: Re: [PATCH] JDK-7033681 - Improve the documentation of Arrays.asList 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}. > * > * <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
