subscriber: document time's --cfg unsound_local_offset (#1699)

## Motivation

The `time` crate must be compiled with `--cfg unsound_local_offset` in
order for local timestamps to be enabled. For users whose first exposure
to the `time` crate's API is via `tracing-subscriber`'s `time` timestamp
formatters, this is potentially _very_ surprising! Therefore, although
this cfg is not part of `tracing`'s API surface, we should probably
document this aspect of `time`'s API in the
`tracing-subscriber::fmt::time` documentation.

## Solution

This branch adds warnings in the `time::LocalTime` type's API docs, in
the struct-level documentation and on the `new` constructor, describing
that `--cfg unsound_local_offset` is necessary to record local
timestamps and referring users to the `time` documentation. I also added
`unsound_local_offset` to the `doc(cfg(...))` attributes for the
`LocalTime` type.

While I was changing `tracing-subscriber`'s docs, I also fixed a couple
formatting issues I noticed.

Fixes #1688

tracing-subscriber/src/fmt/time/mod.rs

@@ -12,7 +12,7 @@ mod time_crate;
 pub use time_crate::UtcTime;
 
 #[cfg(feature = "local-time")]
-#[cfg_attr(docsrs, doc(cfg(feature = "local-time")))]
+#[cfg_attr(docsrs, doc(cfg(unsound_local_offset, feature = "local-time")))]
 pub use time_crate::LocalTime;
 
 /// A type that can measure and format the current time.

tracing-subscriber/src/fmt/time/time_crate.rs

@@ -6,12 +6,26 @@ use time::{format_description::well_known, formatting::Formattable, OffsetDateTi
 ///
 /// To format the current [UTC time] instead, use the [`UtcTime`] type.
 ///
+/// <div class="example-wrap" style="display:inline-block">
+/// <pre class="compile_fail" style="white-space:normal;font:inherit;">
+///     <strong>Warning</strong>: The <a href = "https://docs.rs/time/0.3/time/"><code>time</code>
+///     crate</a> must be compiled with <code>--cfg unsound_local_offset</code> in order to use
+///     local timestamps. When this cfg is not enabled, local timestamps cannot be recorded, and
+///     events will be logged without timestamps.
+///
+///    See the <a href="https://docs.rs/time/0.3.4/time/#feature-flags"><code>time</code>
+///    documentation</a> for more details.
+/// </pre></div>
+///
 /// [local time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_local
 /// [UTC time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_utc
 /// [formatter]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
 /// [`time` crate]: https://docs.rs/time/0.3/time/
 #[derive(Clone, Debug)]
-#[cfg_attr(docsrs, doc(cfg(all(feature = "time", feature = "local-time"))))]
+#[cfg_attr(
+    docsrs,
+    doc(cfg(all(unsound_local_offset, feature = "time", feature = "local-time")))
+)]
 #[cfg(feature = "local-time")]
 pub struct LocalTime<F> {
     format: F,
@@ -62,6 +76,19 @@ impl<F: Formattable> LocalTime<F> {
     /// [`time` crate] with the provided provided format. The format may be any
     /// type that implements the [`Formattable`] trait.
     ///
+    ///
+    /// <div class="example-wrap" style="display:inline-block">
+    /// <pre class="compile_fail" style="white-space:normal;font:inherit;">
+    ///     <strong>Warning</strong>: The <a href = "https://docs.rs/time/0.3/time/">
+    ///     <code>time</code> crate</a> must be compiled with <code>--cfg
+    ///     unsound_local_offset</code> in order to use local timestamps. When this
+    ///     cfg is not enabled, local timestamps cannot be recorded, and
+    ///     events will be logged without timestamps.
+    ///
+    ///    See the <a href="https://docs.rs/time/0.3.4/time/#feature-flags">
+    ///    <code>time</code> documentation</a> for more details.
+    /// </pre></div>
+    ///
     /// Typically, the format will be a format description string, or one of the
     /// `time` crate's [well-known formats].
     ///

tracing-subscriber/src/lib.rs

@@ -60,7 +60,7 @@
 //!   **Requires "std"**.
 //! - `json`: Enables `fmt` support for JSON output. In JSON output, the ANSI
 //!   feature does nothing. **Requires "fmt" and "std"**.
-//! - [`local-time`]: Enables local time formatting when using the [`time`
+//! - `local-time`: Enables local time formatting when using the [`time`
 //!   crate]'s timestamp formatters with the `fmt` subscriber.
 //!
 //! ### Optional Dependencies