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

rgiulietti · 2021-08-02T22:34:58Z

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

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

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

Reviewers

Joe Darcy (@jddarcy - Reviewer)
Brian Burkhalter (@bplb - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/4963/head:pull/4963
$ git checkout pull/4963

Update a local copy of the PR:
$ git checkout pull/4963
$ git pull https://git.openjdk.java.net/jdk pull/4963/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 4963

View PR using the GUI difftool:
$ git pr show -t 4963

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/4963.diff

…in some places

rgiulietti · 2021-08-02T22:35:31Z

/csr

bridgekeeper · 2021-08-02T22:35:39Z

👋 Welcome back rgiulietti! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-08-02T22:37:04Z

@rgiulietti has indicated that a compatibility and specification (CSR) request is needed for this pull request.
@rgiulietti please create a CSR request for issue JDK-8271599. This pull request cannot be integrated until the CSR request is approved.

openjdk · 2021-08-02T22:38:49Z

@rgiulietti The following label will be automatically applied to this pull request:

core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2021-08-02T22:43:41Z

Webrevs

jddarcy · 2021-08-03T22:01:36Z

Looks fine; please make the same edits to StrictMath for a final code review and CSR.

…in some places

bplb · 2021-08-03T22:31:37Z

src/java.base/share/classes/java/lang/Math.java

@@ -1247,7 +1247,7 @@ public static long unsignedMultiplyHigh(long x, long y) {
    /**
     * Returns the largest (closest to positive infinity)
     * {@code int} value that is less than or equal to the algebraic quotient.
-     * There is one special case, if the dividend is the
+     * There is one special case: if the dividend is the


I think the "the" at the end of line 1250 can be deleted.

bplb · 2021-08-03T22:32:41Z

src/java.base/share/classes/java/lang/Math.java

+     *       returns the largest integer less than or equal to the quotient
+     *       while the {@code /} operator returns the smallest integer greater
+     *       than or equal to the quotient.
+     *       There's a difference if and only if the quotient is not an integer.<br>


Maybe "There's a difference" -> "They differ" ?

bplb · 2021-08-03T22:33:09Z

src/java.base/share/classes/java/lang/Math.java

@@ -1290,7 +1292,7 @@ public static int floorDiv(int x, int y) {
    /**
     * Returns the largest (closest to positive infinity)
     * {@code long} value that is less than or equal to the algebraic quotient.
-     * There is one special case, if the dividend is the
+     * There is one special case: if the dividend is the


Again, "the" can go away.

bplb · 2021-08-03T22:33:30Z

src/java.base/share/classes/java/lang/Math.java

@@ -1319,7 +1321,7 @@ public static long floorDiv(long x, int y) {
    /**
     * Returns the largest (closest to positive infinity)
     * {@code long} value that is less than or equal to the algebraic quotient.
-     * There is one special case, if the dividend is the
+     * There is one special case: if the dividend is the


Delete "the" again.

bplb · 2021-08-03T22:36:35Z

src/java.base/share/classes/java/lang/StrictMath.java

@@ -1051,10 +1051,10 @@ public static long unsignedMultiplyHigh(long x, long y) {
    /**
     * Returns the largest (closest to positive infinity)
     * {@code int} value that is less than or equal to the algebraic quotient.
-     * There is one special case, if the dividend is the
+     * There is one special case: if the dividend is the


bplb · 2021-08-03T22:36:58Z

src/java.base/share/classes/java/lang/StrictMath.java

@@ -1075,7 +1075,7 @@ public static int floorDiv(int x, int y) {
    /**
     * Returns the largest (closest to positive infinity)
     * {@code long} value that is less than or equal to the algebraic quotient.
-     * There is one special case, if the dividend is the
+     * There is one special case: if the dividend is the


bplb · 2021-08-03T22:37:12Z

src/java.base/share/classes/java/lang/StrictMath.java

@@ -1099,10 +1099,10 @@ public static long floorDiv(long x, int y) {
    /**
     * Returns the largest (closest to positive infinity)
     * {@code long} value that is less than or equal to the algebraic quotient.
-     * There is one special case, if the dividend is the
+     * There is one special case: if the dividend is the


…in some places

rgiulietti · 2021-08-04T07:41:36Z

@bplb or @jddarcy could you please file a CSR on the JBS for this PR? As I don't have Author status, I'm not entitled to help myself.

Thanks

bplb · 2021-08-04T16:10:47Z

Done yesterday (JDK-8271827).

openjdk · 2021-08-04T16:34:23Z

@rgiulietti This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

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

Reviewed-by: darcy, bpb

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 34 new commits pushed to the master branch:

452f7d7: 8271217: Fix race between G1PeriodicGCTask checks and GC request
221e4b9: 8270797: ShortECDSA.java test is not complete
0a27f26: 8265057: G1: Investigate removal of maintenance of two BOT thresholds
eec64f5: 8256844: Make NMT late-initializable
4df1bc4: 6350025: API documentation for JOptionPane using deprecated methods.
efcdcc7: 8270893: IndexOutOfBoundsException while reading large TIFF file
977b8c4: 8271836: runtime/ErrorHandling/ClassPathEnvVar.java fails with release VMs
04134fc: 8264543: Cross modify fence optimization for x86
9e76909: 8271824: mark hotspot runtime/CompressedOops tests which ignore external VM flags
e49b7d9: 8271828: mark hotspot runtime/classFileParserBug tests which ignore external VM flags
... and 24 more: https://git.openjdk.java.net/jdk/compare/0a85236396c667c8d2c890e4384c623b39455075...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@jddarcy, @bplb) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

rgiulietti · 2021-08-04T16:37:06Z

/integrate

openjdk · 2021-08-04T16:37:58Z

@rgiulietti
Your change (at version 21e4f37) is now ready to be sponsored by a Committer.

bplb · 2021-08-04T17:15:08Z

/sponsor

openjdk · 2021-08-04T17:16:52Z

Going to push as commit 9f1edaf.
Since your change was applied there have been 34 commits pushed to the master branch:

452f7d7: 8271217: Fix race between G1PeriodicGCTask checks and GC request
221e4b9: 8270797: ShortECDSA.java test is not complete
0a27f26: 8265057: G1: Investigate removal of maintenance of two BOT thresholds
eec64f5: 8256844: Make NMT late-initializable
4df1bc4: 6350025: API documentation for JOptionPane using deprecated methods.
efcdcc7: 8270893: IndexOutOfBoundsException while reading large TIFF file
977b8c4: 8271836: runtime/ErrorHandling/ClassPathEnvVar.java fails with release VMs
04134fc: 8264543: Cross modify fence optimization for x86
9e76909: 8271824: mark hotspot runtime/CompressedOops tests which ignore external VM flags
e49b7d9: 8271828: mark hotspot runtime/classFileParserBug tests which ignore external VM flags
... and 24 more: https://git.openjdk.java.net/jdk/compare/0a85236396c667c8d2c890e4384c623b39455075...master

Your commit was automatically rebased without conflicts.

openjdk · 2021-08-04T17:17:07Z

@bplb @rgiulietti Pushed as commit 9f1edaf.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

8271599: Javadoc of floorDiv() and floorMod() families is inaccurate …

423af12

…in some places

openjdk bot added rfr Pull request is ready for review csr Pull request needs approved CSR before integration labels Aug 2, 2021

openjdk bot added the core-libs core-libs-dev@openjdk.org label Aug 2, 2021

rgiulietti mentioned this pull request Aug 3, 2021

8271225: Add floorDivExact() method to java.lang.[Strict]Math #4941

Closed

3 tasks

rgiulietti added 2 commits August 4, 2021 00:20

8271599: Javadoc of floorDiv() and floorMod() families is inaccurate …

cab4c54

…in some places

8271599: Javadoc of floorDiv() and floorMod() families is inaccurate …

dc81446

…in some places

bplb reviewed Aug 3, 2021

View reviewed changes

8271599: Javadoc of floorDiv() and floorMod() families is inaccurate …

21e4f37

…in some places

jddarcy approved these changes Aug 3, 2021

View reviewed changes

bplb approved these changes Aug 4, 2021

View reviewed changes

openjdk bot removed the csr Pull request needs approved CSR before integration label Aug 4, 2021

openjdk bot added the ready Pull request is ready to be integrated label Aug 4, 2021

openjdk bot added the sponsor Pull request is ready to be sponsored label Aug 4, 2021

openjdk bot closed this Aug 4, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review sponsor Pull request is ready to be sponsored labels Aug 4, 2021

rgiulietti deleted the JDK-8271599 branch August 10, 2021 19:45

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

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

rgiulietti commented Aug 2, 2021 •

edited by openjdk bot

rgiulietti commented Aug 2, 2021

bridgekeeper bot commented Aug 2, 2021

openjdk bot commented Aug 2, 2021

openjdk bot commented Aug 2, 2021

mlbridge bot commented Aug 2, 2021 •

edited

jddarcy commented Aug 3, 2021

bplb Aug 3, 2021

bplb Aug 3, 2021

bplb Aug 3, 2021

bplb Aug 3, 2021

bplb Aug 3, 2021

bplb Aug 3, 2021

bplb Aug 3, 2021

rgiulietti commented Aug 4, 2021

bplb commented Aug 4, 2021

openjdk bot commented Aug 4, 2021 •

edited

rgiulietti commented Aug 4, 2021

openjdk bot commented Aug 4, 2021

bplb commented Aug 4, 2021

openjdk bot commented Aug 4, 2021

openjdk bot commented Aug 4, 2021

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

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

Conversation

rgiulietti commented Aug 2, 2021 • edited by openjdk bot

Progress

Issue

Reviewers

Reviewing

rgiulietti commented Aug 2, 2021

bridgekeeper bot commented Aug 2, 2021

openjdk bot commented Aug 2, 2021

openjdk bot commented Aug 2, 2021

mlbridge bot commented Aug 2, 2021 • edited

Webrevs

jddarcy commented Aug 3, 2021

bplb Aug 3, 2021

Choose a reason for hiding this comment

bplb Aug 3, 2021

Choose a reason for hiding this comment

bplb Aug 3, 2021

Choose a reason for hiding this comment

bplb Aug 3, 2021

Choose a reason for hiding this comment

bplb Aug 3, 2021

Choose a reason for hiding this comment

bplb Aug 3, 2021

Choose a reason for hiding this comment

bplb Aug 3, 2021

Choose a reason for hiding this comment

rgiulietti commented Aug 4, 2021

bplb commented Aug 4, 2021

openjdk bot commented Aug 4, 2021 • edited

rgiulietti commented Aug 4, 2021

openjdk bot commented Aug 4, 2021

bplb commented Aug 4, 2021

openjdk bot commented Aug 4, 2021

openjdk bot commented Aug 4, 2021

rgiulietti commented Aug 2, 2021 •

edited by openjdk bot

mlbridge bot commented Aug 2, 2021 •

edited

openjdk bot commented Aug 4, 2021 •

edited