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