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

[Roger Riggs]

On Thu, 20 Jul 2023 19:29:33 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 12 additional commits since the last revision:
>> 
>>  - Improve wording and remove markup for clarity
>>  - Merge branch 'master' into 8310033-time-compareto
>>  - Correct the descriptions to correctly identify the compareTo return
>>    value < 0 as this is before that, and > 0 as this is after that.
>>    Thanks to a careful reviewer spotting my reversing of the conditions.
>>  - Improve the grammar of "the comparator value is" -> "the comparator value, that is"
>>    Thanks for the reminder.
>>  - Merge branch 'master' into 8310033-time-compareto
>>  - Improve descriptions to be more specific and remove inappropriate use of before/after
>>    Remove extra blank lines
>>  - Clarify return values of date time classes
>>  - 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
>>  - ... and 2 more: https://git.openjdk.org/jdk/compare/4ab3be9f...1d39e2d4
>
> src/java.base/share/classes/java/time/OffsetDateTime.java line 1805:
> 
>> 1803:      *
>> 1804:      * @param other  the other date-time to compare to, not null
>> 1805:      * @return the comparator value, that is the comparison with the {@code other}'s instant, if they are not equal;
> 
> This text is incorrect. It does not match the description above re offsets. (This would be a suitable description for `compareInstant`)

Line 1806 describes the comparison of the local time if the instants are equal.
```and if equal to the {@code other}'s instant, the comparison of the {@code other}'s local date-time```

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

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