RFR: JDK-8257086: Clarify differences between {Float, Double}.equals and ==

[Stuart Marks]

On Tue, 8 Dec 2020 16:29:49 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Updates to the specifications of Double.{equals, compareTo} to explain more explicitly why the obvious wrappers around "==" and "<"/"==" are not sufficient for floating-point values.
> 
> Once the wording is worked out, I'll replicate it for the analogous methods on Float.

I'll note initially that the original bug is about `equals` and `==` whereas this change also covers `compareTo` and additional comparison operators `<` and `>`. I believe covering this additional material **IS** important, as these concepts are all closely related.

While this material is covering the right ground, I'd say that it's too verbose for a method specification. It feels like it's being compressed to fit into a method specification and thus doesn't do the topic justice.

(One additional concept that ought to be covered is that `compareTo` is *consistent with equals*. This should be asserted in the method specification, but trying to explain it in a method specification seems difficult.)

I'll suggest a couple alternatives. One is to put a full, combined explanation into class doc somewhere, say in `Double`. The various methods can then make some terse assertions and then refer to the combined explanation. `Float` could refer to `Double` instead of replicating the text.

Another alternative is to put this explanation into the `java.lang` package specification. This might be a good fit, since there is already some explanation there of the boxed primitives.

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

PR: https://git.openjdk.java.net/jdk/pull/1699