RFD: "equal" vs "equivalent" in Float.NaN, Double.NaN

[Eirik Bjørsnøs]

On Fri, Nov 1, 2024 at 8:42 PM Joseph D. Darcy <joe.darcy at oracle.com> wrote:

> A few releases back, a discussion of "quality, equivalence, and comparison
> of floating-point values" was added to java.lang.Double:
>
>
> https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/lang/Double.html#equivalenceRelation
>
> That note discusses the topics in question.
>
Thanks Joe, that's exactly what I was missing. Saying "equivalent to"
without defining the equivalence relation seems to leave room for
confusion.

I see the API note of Float/Double::equals link to this note. Do you think
it would be useful / worthwhile to add a @linkplain from the NaN
descriptions as well, like this?

     /**
      * A constant holding a Not-a-Number (NaN) value of type
-     * {@code float}.  It is equivalent to the value returned by
-     * {@code Float.intBitsToFloat(0x7fc00000)}.
+     * {@code float}.  It is {@linkplain Double##equivalenceRelation
equivalent}
+     * to the value returned by {@code Float.intBitsToFloat(0x7fc00000)}.
      */
     public static final float NaN = 0.0f / 0.0f;

Cheers,
Eirik.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20241101/cbcae863/attachment.htm>