fix doctests

src/fmt/builder.rs

@@ -41,7 +41,7 @@ use crate::layer::JsonLayer;
 /// Using [`init`] to set the default subscriber:
 ///
 /// ```rust
-/// json_subscriber::builder::SubscriberBuilder::default().init();
+/// json_subscriber::fmt::SubscriberBuilder::default().init();
 /// ```
 ///
 /// Configuring the output format:
@@ -80,7 +80,6 @@ use crate::layer::JsonLayer;
 /// ```rust
 /// let subscriber = json_subscriber::fmt()
 ///     .with_max_level(tracing::Level::DEBUG)
-///     .compact()
 ///     .finish();
 ///
 /// tracing::subscriber::with_default(subscriber, || {
@@ -301,7 +300,7 @@ impl<W, T, F> SubscriberBuilder<W, T, F> {
     /// ```
     /// use tracing_subscriber::{fmt::writer::EitherWriter, reload};
     /// # fn main() {
-    /// let subscriber = json_subscriber::fmt::subscriber()
+    /// let subscriber = json_subscriber::fmt()
     ///     .with_writer::<Box<dyn Fn() -> EitherWriter<_, _>>>(Box::new(|| EitherWriter::A(std::io::stderr())));
     /// let (subscriber, reload_handle) = reload::Layer::new(subscriber);
     /// # let subscriber: reload::Layer<_, tracing_subscriber::Registry> = subscriber;
@@ -327,10 +326,7 @@ impl<W, T, F> SubscriberBuilder<W, T, F> {
     /// Using [`TestWriter`] to let `cargo test` capture test output:
     ///
     /// ```rust
-    /// use std::io;
-    /// use json_subscriber::fmt;
-    ///
-    /// let fmt_subscriber = fmt::subscriber()
+    /// let fmt_subscriber = json_subscriber::fmt::fmt()
     ///     .with_test_writer();
     /// ```
     /// [capturing]:
@@ -378,11 +374,10 @@ impl<W, T, F> SubscriberBuilder<W, T, F> {
     ///
     /// ```rust
     /// use tracing::Level;
-    /// use json_subscriber::fmt;
     /// use tracing_subscriber::fmt::writer::MakeWriterExt;
     ///
     /// let stderr = std::io::stderr.with_max_level(Level::WARN);
-    /// let subscriber = fmt::subscriber()
+    /// let subscriber = json_subscriber::fmt::fmt()
     ///     .map_writer(move |w| stderr.or_else(w));
     /// ```
     pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> SubscriberBuilder<W2, T, F>
@@ -747,11 +742,11 @@ impl<W, T, F> SubscriberBuilder<W, T, F> {
     ///
     /// For example:
     ///
-    /// ```
+    /// ```rust
+    /// # use tracing_subscriber::prelude::*;
     /// use tracing::Level;
-    /// use tracing_subscriber::util::SubscriberInitExt;
     ///
-    /// let builder = tracing_subscriber::fmt()
+    /// let builder = json_subscriber::fmt()
     ///      // Set a max level filter on the collector
     ///     .with_max_level(Level::INFO)
     ///     .with_filter_reloading();
@@ -775,7 +770,9 @@ impl<W, T, F> SubscriberBuilder<W, T, F> {
     /// ```
     ///
     /// [`reload_handle`]: Self::reload_handle
-    pub fn with_filter_reloading(self) -> SubscriberBuilder<W, T, reload::Layer<F, Registry>> {
+    #[cfg(feature = "env-filter")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "env-filter")))]
+    pub fn with_filter_reloading<S>(self) -> SubscriberBuilder<W, T, reload::Layer<F, S>> {
         let (filter, _) = reload::Layer::new(self.filter);
         SubscriberBuilder {
             make_writer: self.make_writer,
@@ -798,10 +795,10 @@ impl<W, T, F> SubscriberBuilder<W, T, F> {
     }
 }
 
-impl<W, T, F> SubscriberBuilder<W, T, reload::Layer<F, Registry>> {
+impl<W, T, F, S> SubscriberBuilder<W, T, reload::Layer<F, S>> {
     /// Returns a `Handle` that may be used to reload the constructed collector's
     /// filter.
-    pub fn reload_handle(&self) -> reload::Handle<F, Registry> {
+    pub fn reload_handle(&self) -> reload::Handle<F, S> {
         self.filter.handle()
     }
 }
@@ -1132,4 +1129,35 @@ mod tests {
         let subscriber = SubscriberBuilder::default().finish();
         assert_lookup_span(subscriber)
     }
+
+    #[test]
+    #[cfg(feature = "env-filter")]
+    fn reload_filter_works() {
+        use tracing::Level;
+        use tracing_subscriber::util::SubscriberInitExt;
+
+        let builder = SubscriberBuilder::default()
+            // Set a max level filter on the collector
+            .with_max_level(Level::INFO)
+            .with_filter_reloading();
+
+        // Get a handle for modifying the collector's max level filter.
+        let handle = builder.reload_handle();
+
+        // Finish building the collector, and set it as the default.
+        builder.finish().init();
+
+        // Currently, the max level is INFO, so this event will be disabled.
+        tracing::debug!("this is not recorded!");
+
+        // Use the handle to set a new max level filter.
+        // (this returns an error if the collector has been dropped, which shouldn't
+        // happen in this example.)
+        handle
+            .reload(Level::DEBUG)
+            .expect("the collector should still exist");
+
+        // Now, the max level is INFO, so this event will be recorded.
+        tracing::debug!("this is recorded!");
+    }
 }

src/fmt/layer.rs

@@ -187,14 +187,10 @@ where
     /// Using `stderr` rather than `stdout`:
     ///
     /// ```rust
-    /// use std::io;
-    /// use tracing_subscriber::fmt;
-    ///
-    /// let fmt_subscriber = fmt::subscriber()
-    ///     .with_writer(io::stderr);
-    /// # // this is necessary for type inference.
-    /// # use tracing_subscriber::Subscribe as _;
-    /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default());
+    /// # use tracing_subscriber::prelude::*;
+    /// let layer = json_subscriber::fmt::layer()
+    ///     .with_writer(std::io::stderr);
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     ///
     /// [`MakeWriter`]: MakeWriter
@@ -217,15 +213,13 @@ where
     /// Redirect output to stderr if level is <= WARN:
     ///
     /// ```rust
-    /// use tracing::Level;
-    /// use tracing_subscriber::fmt::{self, writer::MakeWriterExt};
+    /// # use tracing_subscriber::prelude::*;
+    /// use tracing_subscriber::fmt::writer::MakeWriterExt;
     ///
-    /// let stderr = std::io::stderr.with_max_level(Level::WARN);
-    /// let subscriber = fmt::subscriber()
+    /// let stderr = std::io::stderr.with_max_level(tracing::Level::WARN);
+    /// let layer = json_subscriber::fmt::layer()
     ///     .map_writer(move |w| stderr.or_else(w));
-    /// # // this is necessary for type inference.
-    /// # use tracing_subscriber::Subscribe as _;
-    /// # let _ = subscriber.with_collector(tracing_subscriber::registry::Registry::default());
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> Layer<S, W2>
     where
@@ -246,14 +240,12 @@ where
     /// Using [`TestWriter`] to let `cargo test` capture test output:
     ///
     /// ```rust
-    /// use std::io;
-    /// use tracing_subscriber::fmt;
+    /// # use tracing_subscriber::prelude::*;
+    /// use tracing_subscriber::fmt::writer::MakeWriterExt;
     ///
-    /// let fmt_subscriber = fmt::subscriber()
+    /// let layer = json_subscriber::fmt::layer()
     ///     .with_test_writer();
-    /// # // this is necessary for type inference.
-    /// # use tracing_subscriber::Subscribe as _;
-    /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default());
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     /// [capturing]:
     /// https://doc.rust-lang.org/book/ch11-02-running-tests.html#showing-function-output
@@ -284,12 +276,11 @@ where
     /// #   std::io::stdout
     /// # }
     /// # fn main() {
-    /// let subscriber = fmt::subscriber().with_writer(non_blocking(std::io::stderr()));
-    /// let (subscriber, reload_handle) = reload::JsonLayer::new(subscriber);
-    /// #
-    /// # // specifying the Registry type is required
-    /// # let _: &reload::Handle<fmt::JsonLayer<S, W, T> = &reload_handle;
-    /// #
+    /// let layer = json_subscriber::fmt::layer().with_writer(non_blocking(std::io::stderr()));
+    /// let (layer, reload_handle) = reload::Layer::new(layer);
+    ///
+    /// tracing_subscriber::registry().with(layer).init();
+    ///
     /// info!("This will be logged to stderr");
     /// reload_handle.modify(|subscriber| *subscriber.writer_mut() = non_blocking(std::io::stdout()));
     /// info!("This will be logged to stdout");
@@ -308,7 +299,8 @@ where
     ///
     /// # Examples
     /// ```rust
-    /// let mut layer = tracing_json::layer();
+    /// # use tracing_subscriber::prelude::*;
+    /// let mut layer = json_subscriber::layer();
     /// let mut inner = layer.inner_layer_mut();
     ///
     /// inner.add_static_field(
@@ -317,6 +309,8 @@ where
     ///         "hostname": get_hostname(),
     ///     }),
     /// );
+    /// # tracing_subscriber::registry().with(layer);
+    /// # fn get_hostname() -> &'static str { "localhost" }
     /// ```
     ///
     /// [`reload::Handle::modify`]: tracing_subscriber::reload::Handle::modify

src/fmt/mod.rs

@@ -108,6 +108,7 @@ impl Subscriber {
     /// # Examples
     ///
     /// ```rust
+    /// # use json_subscriber::fmt::Subscriber;
     /// let subscriber = Subscriber::builder()
     ///     .with_max_level(tracing::Level::INFO)
     ///     .with_target(false)

src/layer/mod.rs

@@ -223,14 +223,10 @@ where
     /// Using `stderr` rather than `stdout`:
     ///
     /// ```rust
-    /// use std::io;
-    /// use tracing_subscriber::fmt;
-    ///
-    /// let fmt_subscriber = fmt::subscriber()
-    ///     .with_writer(io::stderr);
-    /// # // this is necessary for type inference.
-    /// # use tracing_subscriber::Subscribe as _;
-    /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default());
+    /// # use tracing_subscriber::prelude::*;
+    /// let layer = json_subscriber::JsonLayer::stdout()
+    ///     .with_writer(std::io::stderr);
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     ///
     /// [`MakeWriter`]: MakeWriter
@@ -267,12 +263,11 @@ where
     /// #   std::io::stdout
     /// # }
     /// # fn main() {
-    /// let subscriber = fmt::subscriber().with_writer(non_blocking(std::io::stderr()));
-    /// let (subscriber, reload_handle) = reload::JsonLayer::new(subscriber);
-    /// #
-    /// # // specifying the Registry type is required
-    /// # let _: &reload::Handle<fmt::JsonLayer<S, W, T> = &reload_handle;
-    /// #
+    /// let layer = json_subscriber::JsonLayer::stdout().with_writer(non_blocking(std::io::stderr()));
+    /// let (layer, reload_handle) = reload::Layer::new(layer);
+    ///
+    /// tracing_subscriber::registry().with(layer).init();
+    ///
     /// info!("This will be logged to stderr");
     /// reload_handle.modify(|subscriber| *subscriber.writer_mut() = non_blocking(std::io::stdout()));
     /// info!("This will be logged to stdout");
@@ -294,14 +289,10 @@ where
     /// Using [`TestWriter`] to let `cargo test` capture test output:
     ///
     /// ```rust
-    /// use std::io;
-    /// use tracing_subscriber::fmt;
-    ///
-    /// let fmt_subscriber = fmt::subscriber()
+    /// # use tracing_subscriber::prelude::*;
+    /// let layer = json_subscriber::JsonLayer::stdout()
     ///     .with_test_writer();
-    /// # // this is necessary for type inference.
-    /// # use tracing_subscriber::Subscribe as _;
-    /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default());
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     /// [capturing]:
     /// https://doc.rust-lang.org/book/ch11-02-running-tests.html#showing-function-output
@@ -338,15 +329,13 @@ where
     /// Redirect output to stderr if level is <= WARN:
     ///
     /// ```rust
-    /// use tracing::Level;
-    /// use tracing_subscriber::fmt::{self, writer::MakeWriterExt};
+    /// # use tracing_subscriber::prelude::*;
+    /// use tracing_subscriber::fmt::writer::MakeWriterExt;
     ///
-    /// let stderr = std::io::stderr.with_max_level(Level::WARN);
-    /// let subscriber = fmt::subscriber()
+    /// let stderr = std::io::stderr.with_max_level(tracing::Level::WARN);
+    /// let layer = json_subscriber::JsonLayer::stdout()
     ///     .map_writer(move |w| stderr.or_else(w));
-    /// # // this is necessary for type inference.
-    /// # use tracing_subscriber::Subscribe as _;
-    /// # let _ = subscriber.with_collector(tracing_subscriber::registry::Registry::default());
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> JsonLayer<S, W2>
     where
@@ -367,16 +356,14 @@ where
     ///
     /// ```rust
     /// # use tracing_subscriber::prelude::*;
-    /// # use tracing_subscriber::registry;
     /// let mut layer = json_subscriber::JsonLayer::stdout();
     /// layer.add_static_field(
     ///     "hostname",
     ///     serde_json::json!({
     ///         "hostname": get_hostname(),
     ///     }),
     /// );
-    ///
-    /// registry().with(layer);
+    /// # tracing_subscriber::registry().with(layer);
     /// # fn get_hostname() -> &'static str { "localhost" }
     /// ```
     pub fn add_static_field(&mut self, key: impl Into<String>, value: serde_json::Value) {
@@ -397,15 +384,14 @@ where
     ///
     /// ```rust
     /// # use tracing_subscriber::prelude::*;
-    /// # use tracing_subscriber::registry;
     /// let mut layer = json_subscriber::JsonLayer::stdout();
     /// layer.add_static_field(
     ///     "deleteMe",
     ///     serde_json::json!("accident"),
     /// );
     /// layer.remove_field("deleteMe");
     ///
-    /// registry().with(layer);
+    /// # tracing_subscriber::registry().with(layer);
     /// ```
     pub fn remove_field(&mut self, key: impl Into<String>) {
         self.schema.remove(&SchemaKey::from(key.into()));

src/lib.rs

@@ -21,7 +21,8 @@
 //! ```rust
 //! use tracing::info;
 //! use json_subscriber;
-//!
+//! #
+//! # mod yak_shave { pub fn shave_all(n: u32) -> u32 { n } }
 //!
 //! // install global collector configured based on RUST_LOG env var.
 //! json_subscriber::fmt::init();
@@ -63,6 +64,8 @@
 //! `tracing-opentelemetry` layer.
 //!
 //! ```rust
+//! # #[cfg(opentelemetry)]
+//! # {
 //! let tracer = todo!();
 //! let opentelemetry = tracing_opentelemetry::layer().with_tracer(tracer);
 //! let json = json_subscriber::layer()
@@ -74,6 +77,7 @@
 //!     .with(opentelemetry)
 //!     .with(json)
 //!     .init();
+//! # }
 //! ```
 //!
 //! This will produce log lines like for example this (without the formatting):