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

[Chen Liang]

On Thu, 18 Sep 2025 03:31:30 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add a total that the total order used by {Double, Float}.compareTo is different than the total order defined by IEEE 754, starting the 2008 version of that standard.

src/java.base/share/classes/java/lang/Double.java line 1443:

> 1441:      * that is NaN representations whose sign bit is set, to be less
> 1442:      * than any finite or infinite value, including negative
> 1443:      * infinity. Also in the IEEE 754 ordering, "positive" NaN values

This last sentence seems redundant because the behavior for positive NaN values are the same for both total orders.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27356#discussion_r2357501879