From ae007f9eb6878b37db22969f5c19c2942fdef5ec Mon Sep 17 00:00:00 2001
From: David Barsky <me@davidbarsky.com>
Date: Thu, 21 Sep 2023 10:20:35 -0500
Subject: [PATCH] edit docs, add constructors for `ChronoLocal` and `ChronoUtc`

---
 .../src/fmt/time/chrono_crate.rs              | 54 ++++++++++++++++++-
 tracing-subscriber/src/fmt/time/mod.rs        | 14 ++++-
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/tracing-subscriber/src/fmt/time/chrono_crate.rs b/tracing-subscriber/src/fmt/time/chrono_crate.rs
index 8dc275fd49..ca1162bb07 100644
--- 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
index d3e7aadca8..dacf7531e3 100644
--- 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.
 ///