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

[Pavel Rappo]

On Sun, 18 Jun 2023 20:26:04 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
>
> As things stand, this PR makes things worse not better I'm afraid.

> @jodastephen Please review updated descriptions. Thanks

I'm not @jodastephen, obviously, but we both suggested doing something with punctuation/grammar as this reads funny/peculiar:

    @return the comparator value is less than zero

Maybe our suggestions got lost in this huge discussion, or you've decided to address them later.

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

PR Comment: https://git.openjdk.org/jdk/pull/14479#issuecomment-1624431201