Summary

Correcting misleading javadoc in DateTimeFormatterBuilder.appendZoneId() and similar methods about parsing zones prefixed with "UT", "UTC", or "GMT".

Problem

When parsing a ZoneId with DateTimeFormatter, a ZoneId is returned if the input is a recognized zoneid; if only an offset is present, a ZoneOffset is returned. The method description for those methods describe the obsolete/incorrect behavior from the past, i.e, as if a ZoneOffset would be returned where ZoneRegion is actually returned for offsets prefixed by "UT", "UTC", or "GMT".

Solution

Align the javadoc for those methods with the existing behavior. Also, clarify that appendZoneRegionId() rejects the ZoneOffset only on formatting in the first paragraph.

Specification

Change the method description in appendZoneId() as:

@@ -1095,18 +1095,18 @@
       * section of the formatter is optional.
       * <p>
       * 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
       * region-based, such as 'Europe/London'. These are parsed differently.
-      * If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser
-      * expects an offset-based zone and will not match region-based zones.
-      * The offset ID, such as '+02:30', may be at the start of the parse,
-      * or prefixed by  'UT', 'UTC' or 'GMT'. The offset ID parsing is
-      * equivalent to using {@link #appendOffset(String, String)} using the
-      * arguments 'HH:MM:ss' and the no offset string '0'.
-      * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot
-      * match a following offset ID, then {@link ZoneOffset#UTC} is selected.
+      * If the parse starts with '+' or '-', then the parser expects an
+      * offset-based zone and will not match region-based zones. The offset
+      * ID parsing is equivalent to using {@link #appendOffset(String, String)}
+      * using the arguments 'HH:MM:ss' and the no offset string '0'.
+      * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser can
+      * match a following offset, then a region-based zone with the parsed
+      * offset will be returned, or else if the parser cannot match a following
+      * offset, then {@link ZoneOffset#UTC} is selected.
       * 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
       * starts with 'Z', then {@code ZoneOffset.UTC} is selected.
       * The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
       * <p>
@@ -1116,13 +1116,13 @@
       *   "Z"                       -- ZoneOffset.UTC
       *   "UT"                      -- ZoneId.of("UT")
       *   "UTC"                     -- ZoneId.of("UTC")
       *   "GMT"                     -- ZoneId.of("GMT")
       *   "+01:30"                  -- ZoneOffset.of("+01:30")
-      *   "UT+01:30"                -- ZoneOffset.of("+01:30")
-      *   "UTC+01:30"               -- ZoneOffset.of("+01:30")
-      *   "GMT+01:30"               -- ZoneOffset.of("+01:30")
+      *   "UT+01:30"                -- ZoneId.of("UT+01:30")
+      *   "UTC+01:30"               -- ZoneId.of("UTC+01:30")
+      *   "GMT+01:30"               -- ZoneId.of("GMT+01:30")
       * </pre>
       *
       * @return this, for chaining, not null
       * @see #appendZoneRegionId()
       */

Change the method description in appendZoneRegionId() as:

@@ -1133,12 +1133,11 @@

      /**
       * Appends the time-zone region ID, such as 'Europe/Paris', to the formatter,
       * rejecting the zone ID if it is a {@code ZoneOffset}.
       * <p>
-      * This appends an instruction to format/parse the zone ID to the builder
-      * only if it is a region-based ID.
+      * This appends an instruction to format only region-based zone IDs to the builder.
       * <p>
       * During formatting, the zone is obtained using a mechanism equivalent
       * to querying the temporal with {@link TemporalQueries#zoneId()}.
       * If the zone is a {@code ZoneOffset} or it cannot be obtained then
       * an exception is thrown unless the section of the formatter is optional.
@@ -1146,18 +1146,18 @@
       * the zone ID from {@link ZoneId#getId()}.
       * <p>
       * 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
       * region-based, such as 'Europe/London'. These are parsed differently.
-      * If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser
-      * expects an offset-based zone and will not match region-based zones.
-      * The offset ID, such as '+02:30', may be at the start of the parse,
-      * or prefixed by  'UT', 'UTC' or 'GMT'. The offset ID parsing is
-      * equivalent to using {@link #appendOffset(String, String)} using the
-      * arguments 'HH:MM:ss' and the no offset string '0'.
-      * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot
-      * match a following offset ID, then {@link ZoneOffset#UTC} is selected.
+      * If the parse starts with '+' or '-', then the parser expects an
+      * offset-based zone and will not match region-based zones. The offset
+      * ID parsing is equivalent to using {@link #appendOffset(String, String)}
+      * using the arguments 'HH:MM:ss' and the no offset string '0'.
+      * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser can
+      * match a following offset, then a region-based zone with the parsed
+      * offset will be returned, or else if the parser cannot match a following
+      * offset, then {@link ZoneOffset#UTC} is selected.
       * 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
       * starts with 'Z', then {@code ZoneOffset.UTC} is selected.
       * The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
       * <p>
@@ -1167,13 +1167,13 @@
       *   "Z"                       -- ZoneOffset.UTC
       *   "UT"                      -- ZoneId.of("UT")
       *   "UTC"                     -- ZoneId.of("UTC")
       *   "GMT"                     -- ZoneId.of("GMT")
       *   "+01:30"                  -- ZoneOffset.of("+01:30")
-      *   "UT+01:30"                -- ZoneOffset.of("+01:30")
-      *   "UTC+01:30"               -- ZoneOffset.of("+01:30")
-      *   "GMT+01:30"               -- ZoneOffset.of("+01:30")
+      *   "UT+01:30"                -- ZoneId.of("UT+01:30")
+      *   "UTC+01:30"               -- ZoneId.of("UTC+01:30")
+      *   "GMT+01:30"               -- ZoneId.of("GMT+01:30")
       * </pre>
       * <p>
       * Note that this method is identical to {@code appendZoneId()} except
       * in the mechanism used to obtain the zone.
       * Note also that parsing accepts offsets, whereas formatting will never

Change the method description in appendZoneOrOffsetId() as:

@@ -1204,18 +1204,18 @@
       * section of the formatter is optional.
       * <p>
       * 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
       * region-based, such as 'Europe/London'. These are parsed differently.
-      * If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser
-      * expects an offset-based zone and will not match region-based zones.
-      * The offset ID, such as '+02:30', may be at the start of the parse,
-      * or prefixed by  'UT', 'UTC' or 'GMT'. The offset ID parsing is
-      * equivalent to using {@link #appendOffset(String, String)} using the
-      * arguments 'HH:MM:ss' and the no offset string '0'.
-      * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot
-      * match a following offset ID, then {@link ZoneOffset#UTC} is selected.
+      * If the parse starts with '+' or '-', then the parser expects an
+      * offset-based zone and will not match region-based zones. The offset
+      * ID parsing is equivalent to using {@link #appendOffset(String, String)}
+      * using the arguments 'HH:MM:ss' and the no offset string '0'.
+      * If the parse starts with 'UT', 'UTC' or 'GMT', and the parser can
+      * match a following offset, then a region-based zone with the parsed
+      * offset will be returned, or else if the parser cannot match a following
+      * offset, then {@link ZoneOffset#UTC} is selected.
       * 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
       * starts with 'Z', then {@code ZoneOffset.UTC} is selected.
       * The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
       * <p>
@@ -1225,13 +1225,13 @@
       *   "Z"                       -- ZoneOffset.UTC
       *   "UT"                      -- ZoneId.of("UT")
       *   "UTC"                     -- ZoneId.of("UTC")
       *   "GMT"                     -- ZoneId.of("GMT")
       *   "+01:30"                  -- ZoneOffset.of("+01:30")
-      *   "UT+01:30"                -- ZoneOffset.of("UT+01:30")
-      *   "UTC+01:30"               -- ZoneOffset.of("UTC+01:30")
-      *   "GMT+01:30"               -- ZoneOffset.of("GMT+01:30")
+      *   "UT+01:30"                -- ZoneId.of("UT+01:30")
+      *   "UTC+01:30"               -- ZoneId.of("UTC+01:30")
+      *   "GMT+01:30"               -- ZoneId.of("GMT+01:30")
       * </pre>
       * <p>
       * Note that this method is identical to {@code appendZoneId()} except
       * in the mechanism used to obtain the zone.
       *