From 4882559ae34e3fee2fd1fd14cb9617df68664281 Mon Sep 17 00:00:00 2001
From: Joe Darcy <darcy@openjdk.org>
Date: Mon, 22 Sep 2025 21:30:47 +0000
Subject: [PATCH] 8367942: Add API note discussing Double.compareTo total order
 and IEEE 754 total order

Reviewed-by: rgiulietti
---
 .../share/classes/java/lang/Double.java        | 18 +++++++++++++++++-
 .../share/classes/java/lang/Float.java         |  4 ++++
 .../classes/jdk/incubator/vector/Float16.java  |  5 +++++
 3 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java
index c43ec054661..661a0ceb42b 100644
--- a/src/java.base/share/classes/java/lang/Double.java
+++ b/src/java.base/share/classes/java/lang/Double.java
@@ -1425,13 +1425,29 @@ public final class Double extends Number
      *      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
diff --git a/src/java.base/share/classes/java/lang/Float.java b/src/java.base/share/classes/java/lang/Float.java
index 3ee4f4ce619..ac5ab9ba055 100644
--- a/src/java.base/share/classes/java/lang/Float.java
+++ b/src/java.base/share/classes/java/lang/Float.java
@@ -1253,6 +1253,10 @@ public final class Float extends Number
      * 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
diff --git a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Float16.java b/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Float16.java
index 3202ca2ba25..45dd52175cc 100644
--- a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Float16.java
+++ b/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Float16.java
@@ -969,6 +969,11 @@ public final class Float16
      *      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