Summary

Enhance the documentation of j.u.Formatter to overcome the problem described next.

Problem

The j.u.Formatter doc fails to mention that not all subtypes of TemporalAccessor carry timezone related information.

The conversions %tz, %tZ, and %tc (and %Tz, %TZ, and %Tc) need timezone info. When applying them on a LocalDateTime, for example, a runtime exception is thrown.

Solution

The Javadoc should be enhance to warn about the potential issue when using any of the above conversions on instances of TemporalAccessor.

Specification

--- a/src/java.base/share/classes/java/util/Formatter.java
+++ b/src/java.base/share/classes/java/util/Formatter.java
@@ -438,6 +438,8 @@
  *     {@code long}, {@link Long}, and {@link Date} the time zone used is
  *     the {@linkplain TimeZone#getDefault() default time zone} for this
  *     instance of the Java virtual machine.
+ *     Not all subtypes of {@link TemporalAccessor} carry a time zone, though,
+ *     so using this conversion might throw an {@link IllegalFormatConversionException}.
  *
  * <tr><th scope="row" style="vertical-align:top">{@code 'Z'}
  *     <td> A string representing the abbreviation for the time zone.  This
@@ -446,6 +448,8 @@
  *     the {@linkplain TimeZone#getDefault() default time zone} for this
  *     instance of the Java virtual machine.  The Formatter's locale will
  *     supersede the locale of the argument (if any).
+ *     Not all subtypes of {@link TemporalAccessor} carry a time zone, though,
+ *     so using this conversion might throw an {@link IllegalFormatConversionException}.
  *
  * <tr><th scope="row" style="vertical-align:top">{@code 's'}
  *     <td> Seconds since the beginning of the epoch starting at 1 January 1970
@@ -555,6 +559,8 @@
  * <tr><th scope="row" style="vertical-align:top">{@code 'c'}
  *     <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
  *     e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
+ *     Not all subtypes of {@link TemporalAccessor} carry a time zone, though,
+ *     so using this conversion might throw an {@link IllegalFormatConversionException}.
  *
  * </tbody>
  * </table>
@@ -1726,6 +1732,8 @@
  *     {@code long}, {@link Long}, and {@link Date} the time zone used is
  *     the {@linkplain TimeZone#getDefault() default time zone} for this
  *     instance of the Java virtual machine.
+ *     Not all subtypes of {@link TemporalAccessor} carry a time zone, though,
+ *     so using this conversion might throw an {@link IllegalFormatConversionException}.
  *
  * <tr><th scope="row" style="vertical-align:top">{@code 'Z'}
  *     <td style="vertical-align:top"> <code>'&#92;u005a'</code>
@@ -1735,6 +1743,8 @@
  *     the {@linkplain TimeZone#getDefault() default time zone} for this
  *     instance of the Java virtual machine.  The Formatter's locale will
  *     supersede the locale of the argument (if any).
+ *     Not all subtypes of {@link TemporalAccessor} carry a time zone, though,
+ *     so using this conversion might throw an {@link IllegalFormatConversionException}.
  *
  * <tr><th scope="row" style="vertical-align:top">{@code 's'}
  *     <td style="vertical-align:top"> <code>'&#92;u0073'</code>
@@ -1871,6 +1881,8 @@
  *     <td style="vertical-align:top"> <code>'&#92;u0063'</code>
  *     <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
  *     e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
+ *     Not all subtypes of {@link TemporalAccessor} carry a time zone, though,
+ *     so using this conversion might throw an {@link IllegalFormatConversionException}.
  *
  * </tbody>
  * </table>