RFR: 8310033: Clarify return value of Java Time compareTo methods [v2]

[Roger Riggs]

On Sun, 18 Jun 2023 20:24:07 GMT, Stephen Colebourne <scolebourne at openjdk.org> wrote:

>> Roger Riggs has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision:
>> 
>>  - Use {@code xxx} to highlight the comparison against the arg.
>>    Update copyrights.
>>  - Merge branch 'master' into 8310033-time-compareto
>>  - Clarify for Duration, AbstractChronology, and Chronology
>>  - Correct javadoc of compareInstant
>>  - 8310033: Improve Instant.compareTo javadoc to mention before and after
>>    Refine timeline order to mention before and after
>>    Add javadoc @see tags to isBefore and isAfter methods
>
> src/java.base/share/classes/java/time/MonthDay.java line 678:
> 
>> 676:      *
>> 677:      * @param other  the other month-day to compare to, not null
>> 678:      * @return the comparator value is less than zero if the {@code other} is before,
> 
> Using before/after here could be confusing, as January could be considered to be before or after July (since the year is not defined).

The `isBefore` and `isAfter` methods use that terminology and Month is an enum with defined order January thru December and use the `compareTo` method to compute before/after.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14479#discussion_r1237231956