RFR 8009736: Comparator API cleanup

[Paul Sandoz]

On Jun 12, 2013, at 5:54 PM, Henry Jen <henry.jen at oracle.com> wrote:
>> 
>> Comparator.reverseOrder
>> 
>> +     * <p>The returned comparator is serializable. Try to compare null with
>> +     * returned comparator will throw {@link NullPointerException}.
>> +     *
>> 
>> Typo "Try to compare" (and to . Do you mean:
>> 
>> The compare method of the returned comparator will throw a  {@link NullPointerException} if a {@code null} value is passed as the second parameter.
>> 
>> ?
>> 
>> Perhaps add a "@See Collections#reverseOrder" and vice versa on that method.
>> 
>> Similar issue for Comparator.naturalOrder but for null passed as the first parameter.
>> 
> 
> Is "compare null using" better then "compare null with"?
> 

It's more the tense of the sentence.

How about:

"The returned comparator is serializable and does not permit null arguments when comparing objects".

?


> null passed as an argument will cause NPE on returned comparator, regardless position.
> 

Doh!, of course :-) Comparable.compare(null) should also throw an NPE, just the stack trace will be slightly different.


>> Map.comparingByKey/Value(Comparator<? super K/V> cmp)
>> 
>> You don't mention "Note that a null key/value…"
>> 
> 
> That's because null is handled by Comparator in this case, if the Comparator is null-friendly, it is fine. Perhaps I should make that clear.

Ah, yes, some clarification would be useful.

Paul.