On 4/7/17 11:44 AM, Brian Burkhalter wrote:
On Apr 6, 2017, at 7:09 PM, Stuart Marks <stuart.ma...@oracle.com
<mailto:stuart.ma...@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.
