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
