RFR: 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in some places [v3]

[Brian Burkhalter]

On Tue, 3 Aug 2021 22:37:12 GMT, Raffaello Giulietti <github.com+70726043+rgiulietti at 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