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