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

[Joe Darcy]

On Mon, 22 Sep 2025 17:02:44 GMT, Raffaello Giulietti <rgiulietti at openjdk.org> wrote:

> 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?

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

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