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

[Daniel Fuchs]

On Tue, 9 Feb 2021 06:42:26 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> A follow-up of sorts to JDK-8257086, this change aims to improve the discussion of the relationship between Object.equals and compareTo and compare methods. The not-consistent-with-equals natural ordering of BigDecimal get more explication too. While updating Object, I added some uses of apiNote and implSpec, as appropriate. While a signum method did not exist when Comparable was added, it has existed for many years so I removed obsolete text that defined a "sgn" function to compute signum.
> 
> Once the changes are agreed to, I'll reflow paragraphs and update the copyright years.

Small typos...

src/java.base/share/classes/java/lang/Object.java line 81:

> 79:      *     This integer need not remain consistent from one execution of an
> 80:      *     application to another execution of the same application.
> 81:      * <li>If two objects are equal according to the {@link equals(Object) equals}

I believe that should be: `{@link #equals(Object) equals}` (same a few line below).

src/java.base/share/classes/java/math/BigDecimal.java line 81:

> 79:  * modes of operation of the arithmetic defined in ANSI X3.274-1996
> 80:  * and ANSI X3.274-1996/AM 1-2000 (section 7.4).  Unlike those
> 81:  * standards, {@code BigDecimal} includes many rounding modes

Missing period at the end of the sentence (after "rounding modes")?

src/java.base/share/classes/java/math/BigDecimal.java line 91:

> 89:  * used in the result's representation.
> 90: 
> 91:  * The different representations of same numerical value are called

Should that be:
The different representations of *a* same numerical value are called ...  - or maybe value is missing a 's'?

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

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