RFR: 8310033: Clarify return value of Java Time compareTo methods

[Lance Andersen]

On Wed, 14 Jun 2023 20:35:54 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

> In java.time packages, clarify timeline order javadoc to mention "before" and "after" in the value of the `compareTo` method return values. 
> Add javadoc @see tags to isBefore and isAfter methods
> 
> Replace use of "negative" and positive with "less than zero" and "greater than zero" in javadoc @return
> The term "positive" is ambiguous, zero is considered positive and indicates equality.

src/java.base/share/classes/java/time/Duration.java line 1422:

> 1420:      *
> 1421:      * @param otherDuration the other duration to compare to, not null
> 1422:      * @return the comparator value is less than zero if the other duration is before,

General comment.  I am not sure that "other duration" is quite clear.  It seems that javadoc for many `compareTo` methods have not standardized on wording for describing the argument being checked.   Some include "argument" when the documentation.    Perhaps change "other duration" -> "duration argument"?

I think LocalDate::compareTo and its use of "other" is perhaps a better  example of why we might want to beef the wording up a bit

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

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