Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 4 commits into from

Conversation

rgiulietti
Copy link
Contributor

@rgiulietti rgiulietti commented Aug 2, 2021

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

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

@rgiulietti
Copy link
Contributor Author

@rgiulietti rgiulietti commented Aug 2, 2021

/csr

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Aug 2, 2021

👋 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 openjdk bot added rfr csr labels Aug 2, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Aug 2, 2021

@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
Copy link

@openjdk openjdk bot commented Aug 2, 2021

@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.

@openjdk openjdk bot added the core-libs label Aug 2, 2021
@mlbridge
Copy link

@mlbridge mlbridge bot commented Aug 2, 2021

Webrevs

@jddarcy
Copy link
Member

@jddarcy jddarcy commented Aug 3, 2021

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

@@ -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
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* 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>
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -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
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, "the" can go away.

@@ -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
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delete "the" again.

@@ -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
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the"

@@ -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
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the"

@@ -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
Copy link
Member

@bplb bplb Aug 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the"

jddarcy
jddarcy approved these changes Aug 3, 2021
bplb
bplb approved these changes Aug 4, 2021
@rgiulietti
Copy link
Contributor Author

@rgiulietti rgiulietti commented Aug 4, 2021

@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
Copy link
Member

@bplb bplb commented Aug 4, 2021

Done yesterday (JDK-8271827).

@openjdk openjdk bot removed the csr label Aug 4, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Aug 4, 2021

@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).

@openjdk openjdk bot added the ready label Aug 4, 2021
@rgiulietti
Copy link
Contributor Author

@rgiulietti rgiulietti commented Aug 4, 2021

/integrate

@openjdk openjdk bot added the sponsor label Aug 4, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Aug 4, 2021

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

@bplb
Copy link
Member

@bplb bplb commented Aug 4, 2021

/sponsor

@openjdk
Copy link

@openjdk openjdk bot commented Aug 4, 2021

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 openjdk bot closed this Aug 4, 2021
@openjdk openjdk bot added integrated and removed ready rfr sponsor labels Aug 4, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Aug 4, 2021

@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.

@rgiulietti rgiulietti deleted the JDK-8271599 branch Aug 10, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
core-libs integrated
3 participants