Skip to content

Commit

Permalink
subscriber: add more cross-references to documentation (#1553)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
davidbarsky committed Mar 18, 2022
1 parent 43e389c commit 254c7a4
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 5 deletions.
12 changes: 7 additions & 5 deletions tracing-subscriber/src/filter/mod.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
24 changes: 24 additions & 0 deletions tracing-subscriber/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
12 changes: 12 additions & 0 deletions tracing-subscriber/src/subscribe/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 254c7a4

Please sign in to comment.