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

[Lance Andersen]

On Fri, 16 Jun 2023 20:51:42 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> 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?

I think that would be fine as well as then it is clear we are referring to the argument.

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

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