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
