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

[Joe Darcy]

On Thu, 18 Sep 2025 04:44:28 GMT, Chen Liang <liach 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.

Hmm. Yeah, I wanted to avoid giving too much details on what IEEE 754 does here; they also ascribe ordering between different NaN bit patterns while Double.compareTo puts all NaNs into the same equivalence class. I'll take another run at the text; thanks.

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

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