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

[Joe Darcy]

On Tue, 8 Dec 2020 17:59:41 GMT, Stuart Marks <smarks 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.

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


I added discussion of compareTo as well as equals to the scope of the bug since they are sibling surprising deviations from what is expected and have the same root cause. (I took care to say "incomplete order" rather than "partial order" since a partial order requires reflexivity.)

The interface java.lang.Comparable gives a definition of "consistent with equals." I didn't verify it doesn't have an anchor to link to, but we don't typically link to the definition. However, I wouldn't be adverse to having "consistent with equals" link to Comparable; that would be more obvious than expecting the reader to follow the "Specified by:  compareTo in interface Comparable<Double>" link javadoc generates for the method.

I think the Float and Double equals and compareTo methods should at least get pointers to any new section added -- I think a standalone section in the package javadoc by itself would have low discoverability.

I'm make another iteration over the text; thanks.

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

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