On Tue, 16 Sep 2025 17:10:18 GMT, Pavel Rappo <[email protected]> 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
Thanks for your review, Naoto.
> Looks good.
>
> > I might be missing something, but what does IEEE 754 have to do with this?
>
> I was simply mentioning there are cases where zeros are signed. Agree that
> adding zero here is clearer.
In regard to directionality, Duration has these three methods:
* isPositive,
* isNegative,
* isZero
The spec of the former two makes it very clear, that if `d.isPositive() ||
d.isNegative()` then `!d.isZero()`. So, if duration of zero length is an
acceptable method argument, then we need to add "zero" to "positive or
negative" explicitly.
The other cases of "positive or negative" that I mentioned relate to
_components_ of Duration. These components are primitive int and long. And
unless you define a positive int or long value such that its sign bit is 0,
then this, for example, should not feel right
/**
* @serial The number of nanoseconds in the duration, expressed as a
fraction of the
* number of seconds. This is always positive, and never exceeds
999,999,999.
*/
private final int nanos;
Because I know for a fact that `nanos` can be 0.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/27296#issuecomment-3300298919
