<i18n dev> RFR: 8175709: DateTimeFormatterBuilder.appendZoneId() has misleading JavaDoc

[Roger Riggs]

On Thu, 19 Dec 2024 22:12:52 GMT, Naoto Sato <naoto at openjdk.org> wrote:

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

src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java line 1154:

> 1152:      * offset-based zone and will not match region-based zones. The offset
> 1153:      * ID parsing is equivalent to using {@link #appendOffset(String, String)}
> 1154:      * using the arguments 'HH:MM:ss' and the no offset string '0'.

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

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22837#discussion_r1894185376