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

[Roger Riggs]

On Tue, 16 Sep 2025 17:10:18 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review this documentation-only change, which I believe does **NOT** require CSR.
>> 
>> The change touches java.time.** classes that I happen to have been using a lot recently. While the diff is pretty self-describing, here's the summary of what I did:
>> 
>> * used a comma separator for some big integer values, to improve readability;
>> * fixed a few typos and grammar.
>> 
>> While I'm open to discuss the change, I also have some questions. Note: I'm not attempting to address those questions in this PR.
>> 
>> * What's the significance of the second argument in Duration.between(Temporal, Temporal) being exclusive? For example, would the result of the following call be different if the second argument was inclusive?
>> 
>>         Duration.between(Instant.ofEpochSecond(1), Instant.ofEpochSecond(2))
>> 
>>   Are there any cases here where that distinction matters?
>> 
>> * In many cases, the following phrase is used throughout documentation:
>> 
>>     > positive or negative
>> 
>>     While the intent is clearly to stress the directed nature of values, shouldn't we -- for completeness -- also mention zero where applicable?
>> 
>> * What's the significance of title-case for Java Time-Scale? FWIW, the documentation also uses "Java time-scale".
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   An empty commit to kick GHA

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.

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

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