archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-26 14:24:46 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8175709: DateTimeFormatterBuilder.appendZoneId() has misleading JavaDoc

Browse source 
Reviewed-by: rriggs
This commit is contained in:
Naoto Sato 2025-01-07 17:40:01 +00:00
parent 030149fec4
commit 9702accdd9
1 changed files with 34 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

69
src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java
View file

@ -1097,14 +1097,14 @@ public final class DateTimeFormatterBuilder {
* During parsing, the text must match a known zone or offset. * During parsing, the text must match a known zone or offset.
* There are two types of zone ID, offset-based, such as '+01:30' and * There are two types of zone ID, offset-based, such as '+01:30' and
* region-based, such as 'Europe/London'. These are parsed differently. * region-based, such as 'Europe/London'. These are parsed differently.
* If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser * If the parse starts with '+' or '-', then the parser expects an
* expects an offset-based zone and will not match region-based zones. * offset-based zone and will not match region-based zones. The offset
* The offset ID, such as '+02:30', may be at the start of the parse, * ID parsing is equivalent to using {@link #appendOffset(String, String)}
* or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is * using the arguments 'HH:MM:ss' and the no offset string '0'.
* equivalent to using {@link #appendOffset(String, String)} using the * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser can
* arguments 'HH:MM:ss' and the no offset string '0'. * match a following offset, then a region-based zone with the parsed
* If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot * offset will be returned, or else if the parser cannot match a following
* match a following offset ID, then {@link ZoneOffset#UTC} is selected. * offset, then {@link ZoneOffset#UTC} is selected.
* In all other cases, the list of known region-based zones is used to * In all other cases, the list of known region-based zones is used to
* find the longest available match. If no match is found, and the parse * find the longest available match. If no match is found, and the parse
* starts with 'Z', then {@code ZoneOffset.UTC} is selected. * starts with 'Z', then {@code ZoneOffset.UTC} is selected.
@ -1118,9 +1118,9 @@ public final class DateTimeFormatterBuilder {
* "UTC" -- ZoneId.of("UTC") * "UTC" -- ZoneId.of("UTC")
* "GMT" -- ZoneId.of("GMT") * "GMT" -- ZoneId.of("GMT")
* "+01:30" -- ZoneOffset.of("+01:30") * "+01:30" -- ZoneOffset.of("+01:30")
* "UT+01:30" -- ZoneOffset.of("+01:30") * "UT+01:30" -- ZoneId.of("UT+01:30")
* "UTC+01:30" -- ZoneOffset.of("+01:30") * "UTC+01:30" -- ZoneId.of("UTC+01:30")
* "GMT+01:30" -- ZoneOffset.of("+01:30") * "GMT+01:30" -- ZoneId.of("GMT+01:30")
* </pre> * </pre>
* *
* @return this, for chaining, not null * @return this, for chaining, not null
@ -1135,8 +1135,7 @@ public final class DateTimeFormatterBuilder {
* Appends the time-zone region ID, such as 'Europe/Paris', to the formatter, * Appends the time-zone region ID, such as 'Europe/Paris', to the formatter,
* rejecting the zone ID if it is a {@code ZoneOffset}. * rejecting the zone ID if it is a {@code ZoneOffset}.
* <p> * <p>
* This appends an instruction to format/parse the zone ID to the builder * This appends an instruction to format only region-based zone IDs to the builder.
* only if it is a region-based ID.
* <p> * <p>
* During formatting, the zone is obtained using a mechanism equivalent * During formatting, the zone is obtained using a mechanism equivalent
* to querying the temporal with {@link TemporalQueries#zoneId()}. * to querying the temporal with {@link TemporalQueries#zoneId()}.
@ -1148,14 +1147,14 @@ public final class DateTimeFormatterBuilder {
* During parsing, the text must match a known zone or offset. * During parsing, the text must match a known zone or offset.
* There are two types of zone ID, offset-based, such as '+01:30' and * There are two types of zone ID, offset-based, such as '+01:30' and
* region-based, such as 'Europe/London'. These are parsed differently. * region-based, such as 'Europe/London'. These are parsed differently.
* If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser * If the parse starts with '+' or '-', then the parser expects an
* expects an offset-based zone and will not match region-based zones. * offset-based zone and will not match region-based zones. The offset
* The offset ID, such as '+02:30', may be at the start of the parse, * ID parsing is equivalent to using {@link #appendOffset(String, String)}
* or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is * using the arguments 'HH:MM:ss' and the no offset string '0'.
* equivalent to using {@link #appendOffset(String, String)} using the * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser can
* arguments 'HH:MM:ss' and the no offset string '0'. * match a following offset, then a region-based zone with the parsed
* If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot * offset will be returned, or else if the parser cannot match a following
* match a following offset ID, then {@link ZoneOffset#UTC} is selected. * offset, then {@link ZoneOffset#UTC} is selected.
* In all other cases, the list of known region-based zones is used to * In all other cases, the list of known region-based zones is used to
* find the longest available match. If no match is found, and the parse * find the longest available match. If no match is found, and the parse
* starts with 'Z', then {@code ZoneOffset.UTC} is selected. * starts with 'Z', then {@code ZoneOffset.UTC} is selected.
@ -1169,9 +1168,9 @@ public final class DateTimeFormatterBuilder {
* "UTC" -- ZoneId.of("UTC") * "UTC" -- ZoneId.of("UTC")
* "GMT" -- ZoneId.of("GMT") * "GMT" -- ZoneId.of("GMT")
* "+01:30" -- ZoneOffset.of("+01:30") * "+01:30" -- ZoneOffset.of("+01:30")
* "UT+01:30" -- ZoneOffset.of("+01:30") * "UT+01:30" -- ZoneId.of("UT+01:30")
* "UTC+01:30" -- ZoneOffset.of("+01:30") * "UTC+01:30" -- ZoneId.of("UTC+01:30")
* "GMT+01:30" -- ZoneOffset.of("+01:30") * "GMT+01:30" -- ZoneId.of("GMT+01:30")
* </pre> * </pre>
* <p> * <p>
* Note that this method is identical to {@code appendZoneId()} except * Note that this method is identical to {@code appendZoneId()} except
@ -1206,14 +1205,14 @@ public final class DateTimeFormatterBuilder {
* During parsing, the text must match a known zone or offset. * During parsing, the text must match a known zone or offset.
* There are two types of zone ID, offset-based, such as '+01:30' and * There are two types of zone ID, offset-based, such as '+01:30' and
* region-based, such as 'Europe/London'. These are parsed differently. * region-based, such as 'Europe/London'. These are parsed differently.
* If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser * If the parse starts with '+' or '-', then the parser expects an
* expects an offset-based zone and will not match region-based zones. * offset-based zone and will not match region-based zones. The offset
* The offset ID, such as '+02:30', may be at the start of the parse, * ID parsing is equivalent to using {@link #appendOffset(String, String)}
* or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is * using the arguments 'HH:MM:ss' and the no offset string '0'.
* equivalent to using {@link #appendOffset(String, String)} using the * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser can
* arguments 'HH:MM:ss' and the no offset string '0'. * match a following offset, then a region-based zone with the parsed
* If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot * offset will be returned, or else if the parser cannot match a following
* match a following offset ID, then {@link ZoneOffset#UTC} is selected. * offset, then {@link ZoneOffset#UTC} is selected.
* In all other cases, the list of known region-based zones is used to * In all other cases, the list of known region-based zones is used to
* find the longest available match. If no match is found, and the parse * find the longest available match. If no match is found, and the parse
* starts with 'Z', then {@code ZoneOffset.UTC} is selected. * starts with 'Z', then {@code ZoneOffset.UTC} is selected.
@ -1227,9 +1226,9 @@ public final class DateTimeFormatterBuilder {
* "UTC" -- ZoneId.of("UTC") * "UTC" -- ZoneId.of("UTC")
* "GMT" -- ZoneId.of("GMT") * "GMT" -- ZoneId.of("GMT")
* "+01:30" -- ZoneOffset.of("+01:30") * "+01:30" -- ZoneOffset.of("+01:30")
* "UT+01:30" -- ZoneOffset.of("UT+01:30") * "UT+01:30" -- ZoneId.of("UT+01:30")
* "UTC+01:30" -- ZoneOffset.of("UTC+01:30") * "UTC+01:30" -- ZoneId.of("UTC+01:30")
* "GMT+01:30" -- ZoneOffset.of("GMT+01:30") * "GMT+01:30" -- ZoneId.of("GMT+01:30")
* </pre> * </pre>
* <p> * <p>
* Note that this method is identical to {@code appendZoneId()} except * Note that this method is identical to {@code appendZoneId()} except