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

@@ -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;

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:

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.
+//!
 //! <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">
@@ -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