JDK 9 RFR(s): 8173152: Wrong wording in Comparator.compare() method spec

[Stuart Marks]

On 4/7/17 11:44 AM, Brian Burkhalter wrote:
> On Apr 6, 2017, at 7:09 PM, Stuart Marks <stuart.marks at oracle.com 
> <mailto:stuart.marks at oracle.com>> wrote:
>
>> -     * imposes orderings that are inconsistent with equals."
>> +     * imposes orderings that are inconsistent with equals."<p>
>
> Picayune question: Would the <p> be better on the line before “In the foregoing?"
The rest of the markup in this method spec has trailing <p> tags, so I just kept 
things consistent with that. This is an odd style but it's not incorrect, as 
every paragraph except for the first has a <p> preceding it.
>
>> +     *
>> +     * In the foregoing description, the notation
>> +     * {@code sgn(}<i>expression</i>{@code )} designates the mathematical
>> +     * <i>signum</i> function, which is defined to return one of {@code -1},
>> +     * {@code 0}, or {@code 1} according to whether the value of
>> +     * <i>expression</i> is negative, zero or positive.
>
> I suggest to put “, respectively” at the end of the sentence.
Sure, I can do that. I'll also add an Oxford comma as well. I'll make the same 
modifications to the Comparable interface, too.

Revised diffs below.

s'marks

# HG changeset patch
# User smarks
# Date 1491598302 25200
#      Fri Apr 07 13:51:42 2017 -0700
# Node ID 1a623ed5238fa04674b74ee92805ec7a1f036fd9
# Parent  7c72114a555820da956c81364ae7ba30698aa799
8173152: Wrong wording in Comparator.compare() method spec
Reviewed-by: XXX

diff -r 7c72114a5558 -r 1a623ed5238f 
src/java.base/share/classes/java/lang/Comparable.java
--- a/src/java.base/share/classes/java/lang/Comparable.java    Fri Mar 31 
14:21:21 2017 -0700
+++ b/src/java.base/share/classes/java/lang/Comparable.java    Fri Apr 07 
13:51:42 2017 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -124,7 +124,7 @@
       * {@code sgn(}<i>expression</i>{@code )} designates the mathematical
       * <i>signum</i> function, which is defined to return one of {@code -1},
       * {@code 0}, or {@code 1} according to whether the value of
-     * <i>expression</i> is negative, zero or positive.
+     * <i>expression</i> is negative, zero, or positive, respectively.
       *
       * @param   o the object to be compared.
       * @return  a negative integer, zero, or a positive integer as this object
diff -r 7c72114a5558 -r 1a623ed5238f 
src/java.base/share/classes/java/util/Comparator.java
--- a/src/java.base/share/classes/java/util/Comparator.java    Fri Mar 31 
14:21:21 2017 -0700
+++ b/src/java.base/share/classes/java/util/Comparator.java    Fri Apr 07 
13:51:42 2017 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -112,12 +112,6 @@
       * zero, or a positive integer as the first argument is less than, equal
       * to, or greater than the second.<p>
       *
-     * In the foregoing description, the notation
-     * {@code sgn(}<i>expression</i>{@code )} designates the mathematical
-     * <i>signum</i> function, which is defined to return one of {@code -1},
-     * {@code 0}, or {@code 1} according to whether the value of
-     * <i>expression</i> is negative, zero or positive.<p>
-     *
       * The implementor must ensure that {@code sgn(compare(x, y)) ==
       * -sgn(compare(y, x))} for all {@code x} and {@code y}.  (This
       * implies that {@code compare(x, y)} must throw an exception if and only
@@ -135,7 +129,13 @@
       * {@code (compare(x, y)==0) == (x.equals(y))}. Generally speaking,
       * any comparator that violates this condition should clearly indicate
       * this fact.  The recommended language is "Note: this comparator
-     * imposes orderings that are inconsistent with equals."
+     * imposes orderings that are inconsistent with equals."<p>
+     *
+     * In the foregoing description, the notation
+     * {@code sgn(}<i>expression</i>{@code )} designates the mathematical
+     * <i>signum</i> function, which is defined to return one of {@code -1},
+     * {@code 0}, or {@code 1} according to whether the value of
+     * <i>expression</i> is negative, zero, or positive, respectively.
       *
       * @param o1 the first object to be compared.
       * @param o2 the second object to be compared.