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

[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

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

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/4963/files
  - new: https://git.openjdk.java.net/jdk/pull/4963/files/dc81446f..21e4f370

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=4963&range=03
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=4963&range=02-03

  Stats: 7 lines in 2 files changed: 0 ins; 0 del; 7 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