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

[Raffaello Giulietti]

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

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

Commit messages:
 - 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in some places

Changes: https://git.openjdk.java.net/jdk/pull/4963/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=4963&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8271599
  Stats: 31 lines in 1 file changed: 4 ins; 7 del; 20 mod
  Patch: https://git.openjdk.java.net/jdk/pull/4963.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/4963/head:pull/4963

PR: https://git.openjdk.java.net/jdk/pull/4963