8367942: Add API note discussing Double.compareTo total order and IEEE 754 total order

Reviewed-by: rgiulietti

Author: jddarcy

src/java.base/share/classes/java/lang/Double.java

@@ -1425,13 +1425,29 @@ public static long doubleToLongBits(double value) {
      *      This method chooses to define positive zero ({@code +0.0d}),
      *      to be greater than negative zero ({@code -0.0d}).
      * </ul>
-
+     *
      * This ensures that the <i>natural ordering</i> of {@code Double}
      * objects imposed by this method is <i>consistent with
      * equals</i>; see {@linkplain ##equivalenceRelation this
      * discussion for details of floating-point comparison and
      * ordering}.
      *
+     * @apiNote
+     * The inclusion of a total order idiom in the Java SE API
+     * predates the inclusion of that functionality in the IEEE 754
+     * standard. The ordering of the totalOrder predicate chosen by
+     * IEEE 754 differs from the total order chosen by this method.
+     * While this method treats all NaN representations as being in
+     * the same equivalence class, the IEEE 754 total order defines an
+     * ordering based on the bit patterns of the NaN among the
+     * different NaN representations. The IEEE 754 order regards
+     * "negative" NaN representations, that is NaN representations
+     * whose sign bit is set, to be less than any finite or infinite
+     * value and less than any "positive" NaN. In addition, the IEEE
+     * order regards all positive NaN values as greater than positive
+     * infinity. See the IEEE 754 standard for full details of its
+     * total ordering.
+     *
      * @param   anotherDouble   the {@code Double} to be compared.
      * @return  the value {@code 0} if {@code anotherDouble} is
      *          numerically equal to this {@code Double}; a value

src/java.base/share/classes/java/lang/Float.java

@@ -1253,6 +1253,10 @@ public static short floatToFloat16(float f) {
      * discussion for details of floating-point comparison and
      * ordering}.
      *
+     * @apiNote
+     * For a discussion of differences between the total order of this
+     * method compared to the total order defined by the IEEE 754
+     * standard, see the note in {@link Double#compareTo(Double)}.
      *
      * @param   anotherFloat   the {@code Float} to be compared.
      * @return  the value {@code 0} if {@code anotherFloat} is

src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Float16.java

@@ -969,6 +969,11 @@ public static Float16 shortBitsToFloat16(short bits) {
      *      to be greater than negative zero.
      * </ul>
      *
+     * @apiNote
+     * For a discussion of differences between the total order of this
+     * method compared to the total order defined by the IEEE 754
+     * standard, see the note in {@link Double#compareTo(Double)}.
+     *
      * @param   anotherFloat16   the {@code Float16} to be compared.
      * @return  the value {@code 0} if {@code anotherFloat16} is
      *          numerically equal to this {@code Float16}; a value