display: clarify default precision in Display impls

Previously, the documentation for `Display` trait implementations on
datetime types discussed precision, but omitted the default behavior.
This PR documents the default behavior and makes the docs for
`Timestamp`, `Zoned`, `civil::DateTime` and `civil::Time` a bit more
consistent.

Fixes #328

Author: BurntSushi

CHANGELOG.md

@@ -22,6 +22,8 @@ Add a "lenient" mode for `strtime` formatting APIs that ignores most errors.
 
 Bug fixes:
 
+* [#328](https://github.com/BurntSushi/jiff/issues/328):
+Document default precision behavior of `Display` impls for datetime types.
 * [#340](https://github.com/BurntSushi/jiff/issues/340):
 Allow whitespace in more places in RFC 2822 parser (improves spec compliance).
 * [#346](https://github.com/BurntSushi/jiff/issues/346):

src/civil/datetime.rs

@@ -2527,13 +2527,32 @@ impl core::fmt::Debug for DateTime {
 
 /// Converts a `DateTime` into an ISO 8601 compliant string.
 ///
-/// Options currently supported:
+/// # Forrmatting options supported
 ///
 /// * [`std::fmt::Formatter::precision`] can be set to control the precision
-/// of the fractional second component.
+/// of the fractional second component. When not set, the minimum precision
+/// required to losslessly render the value is used.
 ///
 /// # Example
 ///
+/// This shows the default rendering:
+///
+/// ```
+/// use jiff::civil::date;
+///
+/// // No fractional seconds:
+/// let dt = date(2024, 6, 15).at(7, 0, 0, 0);
+/// assert_eq!(format!("{dt}"), "2024-06-15T07:00:00");
+///
+/// // With fractional seconds:
+/// let dt = date(2024, 6, 15).at(7, 0, 0, 123_000_000);
+/// assert_eq!(format!("{dt}"), "2024-06-15T07:00:00.123");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// # Example: setting the precision
+///
 /// ```
 /// use jiff::civil::date;
 ///

src/civil/time.rs

@@ -1884,16 +1884,33 @@ impl core::fmt::Debug for Time {
 
 /// Converts a `Time` into an ISO 8601 compliant string.
 ///
-/// Options currently supported:
+/// # Forrmatting options supported
 ///
 /// * [`std::fmt::Formatter::precision`] can be set to control the precision
-/// of the fractional second component.
+/// of the fractional second component. When not set, the minimum precision
+/// required to losslessly render the value is used.
 ///
 /// # Example
 ///
 /// ```
 /// use jiff::civil::time;
 ///
+/// // No fractional seconds:
+/// let t = time(7, 0, 0, 0);
+/// assert_eq!(format!("{t}"), "07:00:00");
+///
+/// // With fractional seconds:
+/// let t = time(7, 0, 0, 123_000_000);
+/// assert_eq!(format!("{t}"), "07:00:00.123");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// # Example: setting the precision
+///
+/// ```
+/// use jiff::civil::time;
+///
 /// let t = time(7, 0, 0, 123_000_000);
 /// assert_eq!(format!("{t:.6}"), "07:00:00.123000");
 /// // Precision values greater than 9 are clamped to 9.

src/timestamp.rs

@@ -2521,10 +2521,29 @@ impl core::fmt::Debug for Timestamp {
 /// # Forrmatting options supported
 ///
 /// * [`std::fmt::Formatter::precision`] can be set to control the precision
-/// of the fractional second component.
+/// of the fractional second component. When not set, the minimum precision
+/// required to losslessly render the value is used.
 ///
 /// # Example
 ///
+/// This shows the default rendering:
+///
+/// ```
+/// use jiff::Timestamp;
+///
+/// // No fractional seconds.
+/// let ts = Timestamp::from_second(1_123_456_789)?;
+/// assert_eq!(format!("{ts}"), "2005-08-07T23:19:49Z");
+///
+/// // With fractional seconds.
+/// let ts = Timestamp::new(1_123_456_789, 123_000_000)?;
+/// assert_eq!(format!("{ts}"), "2005-08-07T23:19:49.123Z");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// # Example: setting the precision
+///
 /// ```
 /// use jiff::Timestamp;
 ///

src/zoned.rs

@@ -3209,13 +3209,32 @@ impl core::fmt::Debug for Zoned {
 
 /// Converts a `Zoned` datetime into a RFC 9557 compliant string.
 ///
-/// Options currently supported:
+/// # Forrmatting options supported
 ///
 /// * [`std::fmt::Formatter::precision`] can be set to control the precision
-/// of the fractional second component.
+/// of the fractional second component. When not set, the minimum precision
+/// required to losslessly render the value is used.
 ///
 /// # Example
 ///
+/// This shows the default rendering:
+///
+/// ```
+/// use jiff::civil::date;
+///
+/// // No fractional seconds:
+/// let zdt = date(2024, 6, 15).at(7, 0, 0, 0).in_tz("US/Eastern")?;
+/// assert_eq!(format!("{zdt}"), "2024-06-15T07:00:00-04:00[US/Eastern]");
+///
+/// // With fractional seconds:
+/// let zdt = date(2024, 6, 15).at(7, 0, 0, 123_000_000).in_tz("US/Eastern")?;
+/// assert_eq!(format!("{zdt}"), "2024-06-15T07:00:00.123-04:00[US/Eastern]");
+///
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// # Example: setting the precision
+///
 /// ```
 /// use jiff::civil::date;
 ///