<i18n dev> RFR: 8367704: Fix minor documentation issues in java.time.** [v6]

[Roger Riggs]

On Tue, 16 Sep 2025 21:55:36 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/java/time/Duration.java line 480:
>> 
>>> 478:      * <p>
>>> 479:      * The result of this method can be a negative duration if the end is before the start.
>>> 480:      * To guarantee a positive or zero duration call {@link #abs()} on the result.
>> 
>> A bit of a quibble here.  Checking the spec of the `isPositive()` method, it does not include zero.
>> If the you intend the "positive" to be the same as the result of the `isPositive` method then I think its best to omit the "zero".  The `abs` method would not change anything to be a zero.
>
> I don't understand. Let's consider an example:
> 
>     jshell> import java.time.*
>     
>     jshell> var i = Instant.now();
>     i ==> 2025-09-16T21:44:06.464393Z
>     
>     jshell> Duration.between(i, i).abs().isPositive()
>     $3 ==> false
> 
> So, `abs()` does not translate any duration into positive duration. There exists duration `d` such that `!d.abs().isPositive()`. Any duration for which `d.equals(Duration.ZERO)` is like that.

Joe's suggestion of "non-negative" (instead of positive) is probably the best replacement.

Mentioning using `abs()` with a zero argument didn't parse well.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27296#discussion_r2355624787