8175709: DateTimeFormatterBuilder.appendZoneId() has misleading JavaDoc

[naotoj]

Clarifying the documentation of DateTimeFormatterBuilder.appendZoneId() and similar methods to align the description with the behavior, in which ZoneOffset is only parsed from the formatter for offset texts without any prefixes. Corresponding CSR has also been drafted.

---

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-8346682 to be approved

Issues

• JDK-8175709: DateTimeFormatterBuilder.appendZoneId() has misleading JavaDoc (Bug - P3)
• JDK-8346682: DateTimeFormatterBuilder.appendZoneId() has misleading JavaDoc (CSR)

Reviewers

• Roger Riggs (@RogerRiggs - Reviewer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 22837

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

Using diff file

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

Using Webrev

Link to Webrev Comment

[bridgekeeper]

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

@naotoj 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:

8175709: DateTimeFormatterBuilder.appendZoneId() has misleading JavaDoc

Reviewed-by: rriggs

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

• 9c393a2: 8346953: Remove unnecessary @SuppressWarnings annotations (client, Make "can write" check work on Windows #2)
• 9a60f44: 8345668: ZoneOffset.ofTotalSeconds performance regression
• 12700cb: 8346264: "Total compile time" counter should include time spent in failing/bailout compiles
• dd81f8d: 8344079: Minor fixes and cleanups to compiler lint-related code
• ccf3d57: 8346985: Convert test/jdk/com/sun/jdi/ClassUnloadEventTest.java to Class-File API
• 594e519: 8346984: Remove ASM-based benchmarks from Class-File API benchmarks
• c027f2e: 8346983: Remove ASM-based transforms from Class-File API tests
• e0695e0: 8346981: Remove obsolete java.base exports of jdk.internal.objectweb.asm packages
• dfaa891: 8346569: Shenandoah: Worker initializes ShenandoahThreadLocalData twice results in memory leak
• f1d85ab: 8346773: Fix unmatched brackets in some misc files
• ... and 86 more: https://git.openjdk.org/jdk/compare/c75b1d4bf65d927e18b10ea6de263a331b78e13a...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.

[openjdk]

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

• 01: Full - Incremental (5439c2c8)
• 00: Full (36d3e8c7)

[RogerRiggs]

The change to drop UT, UTC, GMT, from offset parsing, looks to be correct.
However, it does accept parsing of the offset formatted strings in contradiction to the 2nd paragraph above.

     * This appends an instruction to format/parse the zone ID to the builder
     * only if it is a region-based ID.

This pre-existing text is also isn't clear in that the formatter is always appended to the builder.
The accepting only of a region-based ID occurs when the DateTimeFormatter.parse(...) is parsing.
Perhaps a separate clarification may be useful

[naotoj]

Thanks, Roger. Updated the description per your suggestion.

[RogerRiggs]

lgtm

[naotoj]

Thanks for the review!
/integrate

[openjdk]

Going to push as commit 9702acc.
Since your change was applied there have been 113 commits pushed to the master branch:

• 030149f: 8334644: Automate javax/print/attribute/PageRangesException.java
• c8a9dd3: 8346609: Improve MemorySegment.toString
• 4d8fb80: 8347038: [JMH] jdk.incubator.vector.SpiltReplicate fails NoClassDefFoundError
• cf3e48e: 8346965: Multiple compiler/ciReplay test fails with -XX:+SegmentedCodeCache
• e5f0c19: 8345041: IGV: Free Placement Mode in IGV Layout
• 8b22517: 8211851: (ch) java/nio/channels/AsynchronousSocketChannel/StressLoopback.java times out (aix)
• 5e6cda4: 8347000: Bug in com/sun/net/httpserver/bugs/B6361557.java test
• 3f7052e: 8346868: RISC-V: compiler/sharedstubs tests fail after JDK-8332689
• f119663: 8346573: Can't use custom default file system provider with custom system class loader
• 379ac34: 8346838: RISC-V: runtime/CommandLine/OptionsValidation/TestOptionsWithRanges.java crash with debug VMs
• ... and 103 more: https://git.openjdk.org/jdk/compare/c75b1d4bf65d927e18b10ea6de263a331b78e13a...master

Your commit was automatically rebased without conflicts.

[openjdk]

@naotoj Pushed as commit 9702acc.

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