subscriber: add more cross-references to documentation

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

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.
+//!
 //! <div class="example-wrap" style="display:inline-block">
 //! <pre class="compile_fail" style="white-space:normal;font:inherit;">
 //!     <strong>Warning</strong>: Currently, the <a href="../struct.Registry.html">
@@ -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

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: