From cdb7115e22b342e9ed8c951f3aa9259329f1f746 Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Sun, 12 Sep 2021 14:52:18 -0700 Subject: [PATCH] subscriber: add more cross-references to documentation (#1553) This branch adds some new documentation in a few places that references other sections in the docs. This should help make some of the crate's APIs easier to find. In particular, the crate's top level docs now summarize the `Layer` and `Filter` traits, and link to their individual docs sections. Additionally, the per-layer filtering section in the `Layer` module docs now references some of the concrete `Filter` implementations in the `filter` module. --- tracing-subscriber/src/filter/mod.rs | 6 ++++-- tracing-subscriber/src/layer/mod.rs | 12 ++++++++++++ tracing-subscriber/src/lib.rs | 24 ++++++++++++++++++++++++ 3 files changed, 40 insertions(+), 2 deletions(-) diff --git a/tracing-subscriber/src/filter/mod.rs b/tracing-subscriber/src/filter/mod.rs index 3ceb9f33f9..3e011327e1 100644 --- a/tracing-subscriber/src/filter/mod.rs +++ b/tracing-subscriber/src/filter/mod.rs @@ -1,8 +1,10 @@ //! [`Layer`]s that control which spans and events are enabled by the wrapped //! subscriber. //! -//! For details on filtering spans and events using [`Layer`]s, see the [`layer` -//! module documentation]. +//! This module contains a number of types that provide implementations of +//! various strategies for filtering which spans and events are enabled. For +//! details on filtering spans and events using [`Layer`]s, see the +//! [`layer` module's documentation]. //! //! [`layer` module documentation]: crate::layer#filtering-with-layers //! [`Layer`]: crate::layer diff --git a/tracing-subscriber/src/layer/mod.rs b/tracing-subscriber/src/layer/mod.rs index bbd1756815..90b9ec4728 100644 --- a/tracing-subscriber/src/layer/mod.rs +++ b/tracing-subscriber/src/layer/mod.rs @@ -202,6 +202,14 @@ //! potentially record them. The [`Layer::with_filter`] method combines a //! `Layer` with a [`Filter`], returning a [`Filtered`] layer. //! +//! This crate's [`filter`] module provides a number of types which implement +//! the [`Filter`] trait, such as [`LevelFilter`], [`Targets`], and +//! [`FilterFn`]. These [`Filter`]s provide ready-made implementations of +//! common forms of filtering. For custom filtering policies, the [`FilterFn`] +//! and [`DynFilterFn`] types allow implementing a [`Filter`] with a closure or +//! function pointer. In addition, when more control is required, the [`Filter`] +//! trait may also be implemented for user-defined types. +//! //!
//! 
 //!     Warning: Currently, the 
@@ -396,6 +404,10 @@
 //! [`Layer::enabled`]: Layer::enabled
 //! [`Interest::never()`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/struct.Interest.html#method.never
 //! [`Filtered`]: crate::filter::Filtered
+//! [`filter`]: crate::filter
+//! [`Targets`]: crate::filter::Targets
+//! [`FilterFn`]: crate::filter::FilterFn
+//! [`DynFilterFn`]: crate::filter::DynFilterFn
 //! [level]: tracing_core::Level
 //! [`INFO`]: tracing_core::Level::INFO
 //! [`DEBUG`]: tracing_core::Level::DEBUG
diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs
index 67fa24b0fa..a9059071b7 100644
--- a/tracing-subscriber/src/lib.rs
+++ b/tracing-subscriber/src/lib.rs
@@ -14,6 +14,30 @@
 //!
 //! [msrv]: #supported-rust-versions
 //!
+//! ## `Layer`s and `Filter`s
+//!
+//! The most important component of the `tracing-subscriber` API is the
+//! [`Layer`] trait, which provides a composable abstraction for building
+//! [`Subscriber`]s. Like the [`Subscriber`] trait, a [`Layer`] defines a
+//! particular behavior for collecting trace data. Unlike [`Subscriber`]s,
+//! which implement a *complete* strategy for how trace data is collected,
+//! [`Layer`]s provide *modular* implementations of specific behaviors.
+//! Therefore, they can be [composed together] to form a [`Subscriber`] which is
+//! capable of recording traces in a variety of ways. See the [`layer` module's
+//! documentation][layer] for details on using [`Layer`]s.
+//!
+//! In addition, the [`Filter`] trait defines an interface for filtering what
+//! spans and events are recorded by a particular layer. This allows different
+//! [`Layer`]s to handle separate subsets of the trace data emitted by a
+//! program. See the [documentation on per-layer filtering][plf] for more
+//! information on using [`Filter`]s.
+//!
+//! [`Layer`]: crate::layer::Layer
+//! [composed together]: crate::layer#composing-layers
+//! [layer]: crate::layer
+//! [`Filter`]: crate::layer::Filter
+//! [plf]: crate::layer#per-layer-filtering
+//!
 //! ## Included Subscribers
 //!
 //! The following `Subscriber`s are provided for application authors: