On Tue, 8 Dec 2020 16:29:49 GMT, Joe Darcy <da...@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
