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

[Joe Darcy]

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

>> Okay, I see.
>
> The note itself should be here, but it's demarcated with an `@apiNote` tag. This introduces a subhead "API Note:" in the rendered javadoc. Thus, it's not necessary to start the text with "Note:".

My thinking here was to include the exact string "Note: this class has a natural ordering that is inconsistent with equals." in the text of BigDecimal since that is the phrase java.lang.Comparable recommends. This should improve grep-ability, etc. for such classes in the JDK. The class-level summary has a semantically equivalent statement using different wording, which left the compareTo method as a place to introduce the exact phrase. I use an @apiNote both because it is an informative statement and to prevent the text from necessarily being applied to BigDecimal subclasses. BigDecimal is not final and people can and sometimes do subclass it and those subclasses, in principle, could have a (different) natural order that was consistent with equals.

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

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