On 11/17/17 9:43 PM, John Rose wrote:
Late to the party, but these lines rub me the wrong way:
@return the new {@code List}
@return the new {@code Set}
@return the new {@code Map}
The word "new" is a loaded term, which usually means
(or can be easily mistaken to mean) that a new object
identity is guaranteed. Thus, "new" shouldn't be used
to specify the behavior of value-based classes.
Given that that the underlying objects are of VBCs,
and that we are encouraging programmers to rely on
the efficiency of chained copies, it should say something
like this instead:
@return a {@code List} containing the same elements as the given collection
@return a {@code Set} containing the same elements as the given collection
@return a {@code Map} containing the same mappings as the given map
(Or even s/return a/return an unmodifiable/.)
OK, per your other message, we'll stick with
Collectors.toUnmodifiableList/Set/Map, in the hope that in the future we can
work on improving various incarnations of toList() to have more desirable
properties.
Meanwhile, I agree that "@return the new {@code List}" is wrong and I'll adjust
it (respectively, Set and Map).
Another point from our discussions is that the copyOf() methods should get an
@implNote that says they'll try not to make unnecessary copies.
Also included are some markup changes and a small Set.copyOf implementation
change suggested upthread.
Final(?) webrev:
http://cr.openjdk.java.net/~smarks/reviews/8177290/webrev.3/
Specdiff:
http://cr.openjdk.java.net/~smarks/reviews/8177290/specdiff.3/overview-summary.html
s'marks
