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

[Joe Darcy]

On Fri, 12 Feb 2021 23:31:04 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 typo.
>
> src/java.base/share/classes/java/math/BigDecimal.java line 99:
> 
>> 97:  * hold. The results of methods like {@link scale} and {@link
>> 98:  * unscaledValue} will differ for numerically equal values with
>> 99:  * different representations.
> 
> While this text is correct and reasonable, it doesn't really explain _why_ equals() considers the representation. One might assume incorrectly that the representation is internal only and doesn't affect computations. Of course it does affect computations, which is why I suggested the example. Maybe the example doesn't belong right here, in which case it's reasonable for this change to proceed. I think it would be good to put an example _somewhere_ of non-substitutability of numerical values with different representations. Maybe we could handle that separately.

I've filed DK-8261862: "Expand discussion of rationale for BigDecimal equals/compareTo semantics" as a follow-up bug.

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

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