RFR: JDK-8294539: Augment discussion of equivalence relations on floating-point values [v2]

[Stuart Marks]

On Fri, 30 Sep 2022 17:24:40 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> While the floating-point == operation is *not* an equivalence relation, there are useful equivalence relations that can be defined over floating-point values. Text is added to java.lang.Double to discuss and name those relations.
>
> Joe Darcy has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Add discussion of numerical equality.
>  - Fix typo.

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

> 147:  * equivalence relations can be defined over floating-point
> 148:  * values. Comparing numerical equality to various kinds of
> 149:  * equivalence:

The overall discussion is good, and the inclusion of numerical equality is good, but now this introductory paragraph is invalid. It starts off:

> While `==` is not an equivalence relation,

OK, this continues the discussion, picking up from the assertion several paragraphs above that `==` is not an equivalence relation. Then,

> several useful equivalence relations can be defined over floating-point values. Comparing numerical equality to various kinds of equivalence:

It sounds like what follows will be a list of equivalence relations that will be contrasted with numerical equality, yet the very first example is numerical equality and is _not_ an equivalence relation.

I think this just needs to be reworded to be more inclusive. Maybe something like, "the following is a comparison of various relations among floating-point values."

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

PR: https://git.openjdk.org/jdk/pull/10498