edit docs, add constructors for ChronoLocal and ChronoUtc

davidbarsky · davidbarsky · commit ae007f9eb687 · 2023-09-21T10:20:35.000-05:00
diff --git a/tracing-subscriber/src/fmt/time/chrono_crate.rs b/tracing-subscriber/src/fmt/time/chrono_crate.rs
@@ -28,13 +28,38 @@ impl Default for ChronoFmtType {
     }
 }
 
-/// Retrieve and print the current local time.
+/// Formats the current [local time] using a [formatter] from the [`chrono`] crate.
+///
+/// [local time]: chrono::Local::now()
+/// [formatter]: chrono::format
 #[cfg_attr(docsrs, doc(cfg(feature = "chrono")))]
 #[derive(Debug, Clone, Eq, PartialEq, Default)]
 pub struct ChronoLocal {
     format: ChronoFmtType,
 }
 
+impl ChronoLocal {
+    /// Format the time using the [`RFC 3339`] format
+    /// (a subset of [`ISO 8601`]).
+    ///
+    /// [`RFC 3339`]: https://tools.ietf.org/html/rfc3339
+    /// [`ISO 8601`]: https://en.wikipedia.org/wiki/ISO_8601
+    pub fn rfc_3339() -> Self {
+        Self {
+            format: ChronoFmtType::Rfc3339,
+        }
+    }
+
+    /// Format the time using the given format string.
+    ///
+    /// See [`chrono::format::strftime`] for details on the supported syntax.
+    pub fn new(format_string: String) -> Self {
+        Self {
+            format: ChronoFmtType::Custom(format_string),
+        }
+    }
+}
+
 impl FormatTime for ChronoLocal {
     fn format_time(&self, w: &mut Writer<'_>) -> alloc::fmt::Result {
         let t = chrono::Local::now();
@@ -45,13 +70,38 @@ impl FormatTime for ChronoLocal {
     }
 }
 
-/// Retrieve and print the current UTC time.
+/// Formats the current [UTC time] using a [formatter] from the [`chrono`] crate.
+///
+/// [UTC time]: chrono::Utc::now()
+/// [formatter]: chrono::format
 #[cfg_attr(docsrs, doc(cfg(feature = "chrono")))]
 #[derive(Debug, Clone, Eq, PartialEq, Default)]
 pub struct ChronoUtc {
     format: ChronoFmtType,
 }
 
+impl ChronoUtc {
+    /// Format the time using the [`RFC 3339`] format
+    /// (a subset of [`ISO 8601`]).
+    ///
+    /// [`RFC 3339`]: https://tools.ietf.org/html/rfc3339
+    /// [`ISO 8601`]: https://en.wikipedia.org/wiki/ISO_8601
+    pub fn rfc_3339() -> Self {
+        Self {
+            format: ChronoFmtType::Rfc3339,
+        }
+    }
+
+    /// Format the time using the given format string.
+    ///
+    /// See [`chrono::format::strftime`] for details on the supported syntax.
+    pub fn new(format_string: String) -> Self {
+        Self {
+            format: ChronoFmtType::Custom(format_string),
+        }
+    }
+}
+
 impl FormatTime for ChronoUtc {
     fn format_time(&self, w: &mut Writer<'_>) -> alloc::fmt::Result {
         let t = chrono::Utc::now();
diff --git a/tracing-subscriber/src/fmt/time/mod.rs b/tracing-subscriber/src/fmt/time/mod.rs
@@ -7,6 +7,7 @@ mod datetime;
 
 #[cfg(feature = "time")]
 mod time_crate;
+
 #[cfg(feature = "time")]
 #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
 pub use time_crate::UtcTime;
@@ -15,9 +16,18 @@ pub use time_crate::UtcTime;
 #[cfg_attr(docsrs, doc(cfg(all(unsound_local_offset, feature = "local-time"))))]
 pub use time_crate::LocalTime;
 
-/// [`chrono`]-based implementation for time.
+/// [`chrono`]-based implementation for [`FormatTime`].
+#[cfg(feature = "chrono")]
+#[cfg_attr(docsrs, doc(feature = "local-time"))]
+mod chrono_crate;
+
+#[cfg(feature = "chrono")]
+#[cfg_attr(docsrs, doc(feature = "chrono"))]
+pub use chrono_crate::ChronoLocal;
+
 #[cfg(feature = "chrono")]
-pub mod chrono_crate;
+#[cfg_attr(docsrs, doc(feature = "chrono"))]
+pub use chrono_crate::ChronoUtc;
 
 /// A type that can measure and format the current time.
 ///
