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

[Stuart Marks]

Hi all,

Please review this small javadoc fix to correct the wording in 
Comparator.compare(). There's a sentence defining the sgn() notation, that says 
"In the foregoing description" but it occurs *before* the actual use of sgn(). 
I've moved this to the end of the method spec.

This also makes the Comparator.compare() method spec very similar to the 
Comparable.compareTo() method spec.

Thanks,

s'marks


# HG changeset patch
# User smarks
# Date 1491530800 25200
#      Thu Apr 06 19:06:40 2017 -0700
# Node ID 1f08b6bc20078e07f7264e449a334234906d46e5
# Parent  7c72114a555820da956c81364ae7ba30698aa799
8173152: Wrong wording in Comparator.compare() method spec
Reviewed-by: XXX

diff -r 7c72114a5558 -r 1f08b6bc2007 
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	Thu Apr 06 19:06:40 
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.
       *
       * @param o1 the first object to be compared.
       * @param o2 the second object to be compared.