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

[Brian Burkhalter]

On Tue, 3 Aug 2021 22:44:57 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

Marked as reviewed by bpb (Reviewer).

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

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