fix: correct SerializeField definition and doc formatting (tokio-rs#3040

)

Clippy in 1.80.0 alerted us to the fact that `SerializeField` was never
constructed (and due to its non-`pub` member, it can't be constructed
outside the `tracing-serde` crate where it's from).

This change fixes the definition to hold a reference to a `Field`, which
is what the other `Serialize*` types do. It also implements `AsSerde`
for this type and uses it inside the `SerializeFieldSet` type.

As a bonus, Clippy is now also happy that the type is constructed.

The example collector in the `tracing-serde` crate was also renamed from
`JsonSubscriber` to `JsonCollector`.

Some additional doc formatting issues in `tracing-subscriber` were fixed
so that list items that run to multiple lines are correctly indented.

tracing-serde/src/lib.rs

@@ -71,11 +71,17 @@
 //! use tracing_serde::AsSerde;
 //! use serde_json::json;
 //!
-//! pub struct JsonSubscriber {
+//! pub struct JsonCollector {
 //!     next_id: AtomicUsize, // you need to assign span IDs, so you need a counter
 //! }
 //!
-//! impl Collect for JsonSubscriber {
+//! impl JsonCollector {
+//!     fn new() -> Self {
+//!         Self { next_id: 1.into() }
+//!     }
+//! }
+//!
+//! impl Collect for JsonCollector {
 //!
 //!     fn new_span(&self, attrs: &Attributes<'_>) -> Id {
 //!         let id = self.next_id.fetch_add(1, Ordering::Relaxed);
@@ -97,7 +103,7 @@
 //!     }
 //!
 //!     // ...
-//!     # fn enabled(&self, _: &Metadata<'_>) -> bool { false }
+//!     # fn enabled(&self, _: &Metadata<'_>) -> bool { true }
 //!     # fn enter(&self, _: &Id) {}
 //!     # fn exit(&self, _: &Id) {}
 //!     # fn record(&self, _: &Id, _: &Record<'_>) {}
@@ -107,7 +113,7 @@
 //! ```
 //!
 //! After you implement your `Collector`, you can use your `tracing`
-//! subscriber (`JsonSubscriber` in the above example) to record serialized
+//! collector (`JsonCollector` in the above example) to record serialized
 //! trace data.
 //!
 //! ##  Crate Feature Flags
@@ -188,9 +194,9 @@ use tracing_core::{
 pub mod fields;
 
 #[derive(Debug)]
-pub struct SerializeField(Field);
+pub struct SerializeField<'a>(&'a Field);
 
-impl Serialize for SerializeField {
+impl<'a> Serialize for SerializeField<'a> {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: Serializer,
@@ -209,7 +215,7 @@ impl<'a> Serialize for SerializeFieldSet<'a> {
     {
         let mut seq = serializer.serialize_seq(Some(self.0.len()))?;
         for element in self.0 {
-            seq.serialize_element(element.name())?;
+            seq.serialize_element(&SerializeField(&element))?;
         }
         seq.end()
     }
@@ -532,6 +538,14 @@ impl<'a> AsSerde<'a> for Level {
     }
 }
 
+impl<'a> AsSerde<'a> for Field {
+    type Serializable = SerializeField<'a>;
+
+    fn as_serde(&'a self) -> Self::Serializable {
+        SerializeField(self)
+    }
+}
+
 impl<'a> AsSerde<'a> for FieldSet {
     type Serializable = SerializeFieldSet<'a>;
 
@@ -552,6 +566,8 @@ impl<'a> self::sealed::Sealed for Record<'a> {}
 
 impl<'a> self::sealed::Sealed for Metadata<'a> {}
 
+impl self::sealed::Sealed for Field {}
+
 impl self::sealed::Sealed for FieldSet {}
 
 mod sealed {

tracing-subscriber/src/fmt/fmt_subscriber.rs

@@ -595,7 +595,7 @@ where
     /// # Options
     ///
     /// - [`Subscriber::flatten_event`] can be used to enable flattening event fields into the root
-    /// object.
+    ///   object.
     ///
     #[cfg(feature = "json")]
     #[cfg_attr(docsrs, doc(cfg(feature = "json")))]

tracing-subscriber/src/fmt/format/json.rs

@@ -60,11 +60,11 @@ use tracing_log::NormalizeEvent;
 /// output JSON objects:
 ///
 /// - [`Json::flatten_event`] can be used to enable flattening event fields into
-/// the root
+///   the root
 /// - [`Json::with_current_span`] can be used to control logging of the current
-/// span
+///   span
 /// - [`Json::with_span_list`] can be used to control logging of the span list
-/// object.
+///   object.
 ///
 /// By default, event fields are not flattened, and both current span and span
 /// list are logged.

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

@@ -678,7 +678,7 @@ impl<F, T> Format<F, T> {
     /// # Options
     ///
     /// - [`Format::flatten_event`] can be used to enable flattening event fields into the root
-    /// object.
+    ///   object.
     ///
     #[cfg(feature = "json")]
     #[cfg_attr(docsrs, doc(cfg(feature = "json")))]