On Tue, 3 Aug 2021 22:37:12 GMT, Raffaello Giulietti
<github.com+70726043+rgiulie...@openjdk.org> wrote:
>> Hello,
>>
>> please review the changes in documentation of floorDiv() and floorMod() in
>> all their variants. Some are clarifications, some are corrections.
>>
>> Here's an example of a confusing formulation in the current doc
>>> "the / operator returns the integer closest to zero"
>>
>> Literally, the integer closest to zero is zero!
>>
>>
>> The doc of floorMod(int, int) also states:
>>> "If the signs of arguments are unknown and a positive modulus
>>> is needed it can be computed as (floorMod(x, y) + abs(y)) % abs(y)."
>>
>> That's a questionable advice, as the sum in parentheses can lead to
>> irrecoverable overflow (beside requiring two divisions instead of one).
>> E.g., setting x = Integer.MAX_VALUE - 1, y = Integer.MAX_VALUE leads to the
>> quite incorrect result -3, which is not even positive!
>>
>>
>> Greetings
>> Raffaello
>
> Raffaello Giulietti has updated the pull request incrementally with one
> additional commit since the last revision:
>
> 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in
> some places
src/java.base/share/classes/java/lang/Math.java line 1250:
> 1248: * Returns the largest (closest to positive infinity)
> 1249: * {@code int} value that is less than or equal to the algebraic
> quotient.
> 1250: * There is one special case: if the dividend is the
I think the "the" at the end of line 1250 can be deleted.
src/java.base/share/classes/java/lang/Math.java line 1268:
> 1266: * while the {@code /} operator returns the smallest integer
> greater
> 1267: * than or equal to the quotient.
> 1268: * There's a difference if and only if the quotient is not an
> integer.<br>
Maybe "There's a difference" -> "They differ" ?
src/java.base/share/classes/java/lang/Math.java line 1295:
> 1293: * Returns the largest (closest to positive infinity)
> 1294: * {@code long} value that is less than or equal to the algebraic
> quotient.
> 1295: * There is one special case: if the dividend is the
Again, "the" can go away.
src/java.base/share/classes/java/lang/Math.java line 1324:
> 1322: * Returns the largest (closest to positive infinity)
> 1323: * {@code long} value that is less than or equal to the algebraic
> quotient.
> 1324: * There is one special case: if the dividend is the
Delete "the" again.
src/java.base/share/classes/java/lang/StrictMath.java line 1054:
> 1052: * Returns the largest (closest to positive infinity)
> 1053: * {@code int} value that is less than or equal to the algebraic
> quotient.
> 1054: * There is one special case: if the dividend is the
"the"
src/java.base/share/classes/java/lang/StrictMath.java line 1078:
> 1076: * Returns the largest (closest to positive infinity)
> 1077: * {@code long} value that is less than or equal to the algebraic
> quotient.
> 1078: * There is one special case: if the dividend is the
"the"
src/java.base/share/classes/java/lang/StrictMath.java line 1102:
> 1100: * Returns the largest (closest to positive infinity)
> 1101: * {@code long} value that is less than or equal to the algebraic
> quotient.
> 1102: * There is one special case: if the dividend is the
"the"
-------------
PR: https://git.openjdk.java.net/jdk/pull/4963
