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

[Naoto Sato]

On Fri, 20 Dec 2024 17:09:26 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Naoto Sato has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Reflects review comments
>
> 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

Thanks, Roger. Updated the description per your suggestion.

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

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