RFR: 8261123: Augment discussion of equivalence classes in Object.equals and comparison methods [v3]

[Joe Darcy]

On Thu, 11 Feb 2021 04:09:16 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix typos in javadoc tags found during review.
>
> src/java.base/share/classes/java/lang/Comparable.java line 68:
> 
>> 66:  * orderings that are consistent with equals.  One exception is
>> 67:  * {@link java.math.BigDecimal}, whose {@linkplain java.math.BigDecimal#compareTo natural ordering} equates
>> 68:  * {@code BigDecimal} objects with equal numerical values and different representations
> 
> Nothing here talks about the representation of BigDecimal. I think it would be preferable to say that in BigDecimal, the `equals()` method considers 4.0 and 4.00 unequal because they have different precisions; however, `compareTo()` considers them equal because it considers only their numerical values.

In BigDecimal, I'll add a sentence:

" The results of methods like {@link scale} and {@link unscaledValue} will differ for numerically equal values with different representations."

Talking about "precision" and BigDecimal is more appropriate for pre-JSR 13 BigDecimal since values like zero can have the same precision (1 digit) but many different scales.

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

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