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

[Roger Riggs]

On Fri, 16 Jun 2023 20:47:39 GMT, Lance Andersen <lancea 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

The argument name is `otherDuration` would putting the argument name in {@code} font put sufficient focus on the argument?

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

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