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

[Raffaello Giulietti]

On Mon, 22 Sep 2025 20:47:46 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/Double.java line 1449:
>> 
>>> 1447:      * order regards all positive NaN values as greater than positive
>>> 1448:      * infinity.
>>> 1449:      *
>> 
>> When both arguments are NaNs, IEEE 754 also specifies (§5.10.d.5.ii)
>> 
>>> signaling orders below quiet for +NaN, reverse for −NaN
>> 
>> and leaves more fine grained details to the implementation.
>> 
>> Otherwise looks fine.
>
>> When both arguments are NaNs, IEEE 754 also specifies (§5.10.d.5.ii)
>> 
>> > signaling orders below quiet for +NaN, reverse for −NaN
>> 
>> and leaves more fine grained details to the implementation.
>> 
>> Otherwise looks fine.
> 
> Hmm. I didn't necessarily want to  given all the details of the IEEE 754 total order here, only note that it differs from the total order used in the Java SE API. For example, the entirety of the Java specifications avoid mentioning or explaining the differences between quiet and signaling NaNs and I'd prefer not to get into that here.
> 
> I think adding a blanket statement "see the IEEE 754 standard for full detail on their total order" would satisfy any lingering uncertainty here. What do you think?

Sure, that would clarify any doubt.

The API note mentions negative NaNs, which are not part of the Java spec either. So I came to the conclusion that differentiating between the various NaN categories in IEEE 754 was part of the intent of the note.

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

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