From 254c7a446762c83fb03f3f2c7931dad12efdba84 Mon Sep 17 00:00:00 2001 From: David Barsky Date: Fri, 18 Mar 2022 17:42:49 -0400 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 | 12 +++++++----- tracing-subscriber/src/lib.rs | 24 ++++++++++++++++++++++++ tracing-subscriber/src/subscribe/mod.rs | 12 ++++++++++++ 3 files changed, 43 insertions(+), 5 deletions(-) diff --git a/tracing-subscriber/src/filter/mod.rs b/tracing-subscriber/src/filter/mod.rs index ffb2c26c47..3c7e99cccf 100644 --- a/tracing-subscriber/src/filter/mod.rs +++ b/tracing-subscriber/src/filter/mod.rs @@ -1,11 +1,13 @@ //! [`Subscriber`]s that control which spans and events are enabled by the wrapped -//! subscriber. +//! collector. //! -//! For details on filtering spans and events using [`Subscribe`]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 [`Subscriber`]s, see the +//! [`subscriber` module's documentation]. //! -//! [`layer` module documentation]: crate::layer#filtering-with-layers -//! [`Layer`]: crate::layer +//! [`subscriber` module documentation]: crate::subscribe#filtering-with-layers +//! [`Subscriber`]: crate::subscriber #[cfg(feature = "env-filter")] mod env; mod level; diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs index 18f3deff09..791d0ba511 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 `Collector`s are provided for application authors: diff --git a/tracing-subscriber/src/subscribe/mod.rs b/tracing-subscriber/src/subscribe/mod.rs index 13c0ab1527..475d138b76 100644 --- a/tracing-subscriber/src/subscribe/mod.rs +++ b/tracing-subscriber/src/subscribe/mod.rs @@ -204,6 +204,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 
@@ -398,6 +406,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