On Tue, 8 Dec 2020 22:12:29 GMT, Joe Darcy <da...@openjdk.org> wrote:
>> 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. Great, let me know if you'd like me to provide some text for any particular topics in this area. ------------- PR: https://git.openjdk.java.net/jdk/pull/1699
