JDK-6503196: API doc for DecimalFormat::getMaximumIntegerDigits is unclear

[justin-curtis-lu]

Please review this PR which clarifies some confusion for the digit getter and setter methods of DecimalFormat.

When formatting non BigInteger and BigDecimal values, DecimalFormat uses 309/340 as hard limits for integer and fraction digit limits, regardless of the value set by the user. There was some confusion, that those numbers might be returned by the getters, when in reality, they are only used internally.

Moving the 309/340 wording to the class description and linking to it reduces the repetitive wording, but also eliminates the confusion that the getters may return those values. This should be OK, as setting limits higher than those values are likely rare, so the warning does not need to be in every method description.

Additionally, getMaximumIntegerDigits() is updated to point to the patterns section to warn about the non-obvious rules for max integer digits.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change requires CSR request JDK-8324176 to be approved

Issues

• JDK-6503196: API doc for DecimalFormat::getMaximumIntegerDigits is unclear (Bug - P4)
• JDK-8324176: API doc for DecimalFormat::getMaximumIntegerDigits is unclear (CSR)

Reviewers

• Naoto Sato (@naotoj - Reviewer)
• Iris Clark (@irisclark - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/17541/head:pull/17541
$ git checkout pull/17541

Update a local copy of the PR:
$ git checkout pull/17541
$ git pull https://git.openjdk.org/jdk.git pull/17541/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 17541

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/17541.diff

Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back jlu! 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]

@justin-curtis-lu The following labels will be automatically applied to this pull request:

• core-libs
• i18n

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

[mlbridge]

Webrevs

• 00: Full (91a657ec)

[naotoj]

LGTM

[openjdk]

@justin-curtis-lu 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:

6503196: API doc for DecimalFormat::getMaximumIntegerDigits is unclear

Reviewed-by: naoto, iris

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 60 new commits pushed to the master branch:

• 96607df: 8321545: Override toString() for Format subclasses
• edfee7f: 8323546: Cleanup jcmd docs for Compiler.perfmap and VM.cds filename parameter
• 8b9bf75: 8323515: Create test alias "all" for all test roots
• 3d82363: 8300088: [IMPROVE] OPEN_MAX is no longer the max limit on macOS >= 10.6 for RLIMIT_NOFILE
• 2a01c79: 8324513: Inline ContiguousSpace::object_iterate_from
• fbaaac6: 8314164: java/net/HttpURLConnection/HttpURLConnectionExpectContinueTest.java fails intermittently in timeout
• 791b427: 8323640: [TESTBUG]testMemoryFailCount in jdk/internal/platform/docker/TestDockerMemoryMetrics.java always fail because OOM killed
• bcaad51: 8318228: RISC-V: C2 ConvF2HF
• 5acd37f: 8324207: Serial: Remove Space::set_saved_mark_word
• f5e6d11: 8324210: Serial: Remove unused methods in Generation
• ... and 50 more: https://git.openjdk.org/jdk/compare/51dbd36c74c70b1b17bd73cd2c3253593300b5f0...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.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[justin-curtis-lu]

/integrate

[openjdk]

Going to push as commit 3d32c46.
Since your change was applied there have been 74 commits pushed to the master branch:

• 2d5cb97: 8324647: Invalid test group of lib-test after JDK-8323515
• 6212264: 8320692: Null icon returned for .exe without custom icon
• 32eb529: 8324553: Shenandoah: Move periodic tasks closer to their collaborators
• c702dca: 8323815: Source launcher should find classes with $ in names
• c432dc0: 8322149: ConcurrentHashMap smarter presizing for copy constructor and putAll
• fb822e4: 8324514: ClassLoaderData::print_on should print address of class loader
• 00bb6bf: 8324220: jdk/jfr/event/io/TestSerializationMisdeclarationEvent.java had 22 failures
• bccd823: 8324613: Serial: Rename GenerationPool to TenuredGenerationPool
• 8c003d8: 8321512: runtime/CommandLine/OptionsValidation/TestOptionsWithRanges.java fails on 32-bit platforms
• 67f29b1: 8324537: Remove superfluous _FILE_OFFSET_BITS=64
• ... and 64 more: https://git.openjdk.org/jdk/compare/51dbd36c74c70b1b17bd73cd2c3253593300b5f0...master

Your commit was automatically rebased without conflicts.

[openjdk]

@justin-curtis-lu Pushed as commit 3d32c46.

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