///
/// Note: If a Filter will perform
/// dynamic filtering that depends on the current context in which
@@ -842,7 +838,6 @@ pub trait Filter {
/// enabled method may not be called when a particular instance
/// of that span or event is recorded.
///
- ///
///
/// Note: users of the LookupSpan trait should
/// typically call the span method rather
/// than this method. The span method is implemented by
/// calling span_data, but returns a reference which is
/// capable of performing more sophisiticated queries.
- ///
+//!
//!
//! Note: The thread-local scoped dispatcher (with_default)
//! requires the Rust standard library. no_std users should
//! use set_global_default
//! instead.
-//!
///
/// Note: Although this is implemented for both the
/// Field type and any
diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs
index 372536b100..ca5f93713f 100644
--- a/tracing/src/lib.rs
+++ b/tracing/src/lib.rs
@@ -51,13 +51,13 @@
//! The [`span` module][span]'s documentation provides further details on how to
//! use spans.
//!
-//!
+//!
//! Warning: In asynchronous code that uses async/await syntax,
//! Span::enter may produce incorrect traces if the returned drop
//! guard is held across an await point. See
//! the method documentation
//! for details.
-//!
-//!
-//! Warning: In general, libraries should not call
-//! set_global_default()! Doing so will cause conflicts when
-//! executables that depend on the library try to set the default later.
-//!
+//! Warning: In general, libraries should not call
+//! set_global_default()! Doing so will cause conflicts when
+//! executables that depend on the library try to set the default later.
+//!
//!
//! This subscriber will be used as the default in all threads for the
//! remainder of the duration of the program, similar to setting the logger
@@ -767,12 +766,11 @@
//! [`tracing-elastic-apm`]: https://crates.io/crates/tracing-elastic-apm
//! [Elastic APM]: https://www.elastic.co/apm
//!
-//!
//!
-//! Note: Some of these ecosystem crates are currently
-//! unreleased and/or in earlier stages of development. They may be less stable
-//! than tracing and tracing-core.
-//!
tracing and tracing-core.
+//!
//!
//! ## Crate Feature Flags
//!
@@ -800,14 +798,10 @@
//! tracing = { version = "0.1.27", default-features = false }
//! ```
//!
-//!
-//!
//!
-//! Note: tracing's no_std support
-//! requires liballoc.
-//!
tracing's no_std support
+//! requires liballoc.
+//!
//!
//! ## Supported Rust Versions
//!
diff --git a/tracing/src/span.rs b/tracing/src/span.rs
index c04ec07080..9a60d6f1c7 100644
--- a/tracing/src/span.rs
+++ b/tracing/src/span.rs
@@ -119,13 +119,12 @@
//! });
//! ```
//!
-//!
//!
-//! Note: Since entering a span takes &self, and
-//! Spans are Clone, Send, and
-//! Sync, it is entirely valid for multiple threads to enter the
-//! same span concurrently.
-//!
&self, and
+//! Spans are Clone, Send, and
+//! Sync, it is entirely valid for multiple threads to enter the
+//! same span concurrently.
+//!
//!
//! ## Span Relationships
//!
@@ -649,7 +648,7 @@ impl Span {
/// // This is okay! The span has already been exited before we reach
/// // the await point.
/// some_other_async_function(some_value).await;
- ///
+ ///
/// // ...
/// }
/// ```
@@ -658,7 +657,7 @@ impl Span {
/// attaching a span to a future (async function or block). This will
/// enter the span _every_ time the future is polled, and exit it whenever
/// the future yields.
- ///
+ ///
/// `Instrument` can be used with an async block inside an async function:
/// ```ignore
/// # use tracing::info_span;
@@ -705,13 +704,13 @@ impl Span {
/// # async fn some_other_async_function() {}
/// #[tracing::instrument(level = "info")]
/// async fn my_async_function() {
- ///
+ ///
/// // This is correct! If we yield here, the span will be exited,
/// // and re-entered when we resume.
/// some_other_async_function().await;
///
/// // ...
- ///
+ ///
/// }
/// ```
///
@@ -789,6 +788,14 @@ impl Span {
/// Enters this span, consuming it and returning a [guard][`EnteredSpan`]
/// that will exit the span when dropped.
///
+ ///
+ /// Warning: In asynchronous code that uses async/await syntax,
+ /// Span::entered may produce incorrect traces if the returned drop
+ /// guard is held across an await point. See the
+ /// Span::enter documentation for details.
+ ///
+ ///
+ ///
/// If this span is enabled by the current subscriber, then this function will
/// call [`Subscriber::enter`] with the span's [`Id`], and dropping the guard
/// will call [`Subscriber::exit`]. If the span is disabled, this does
@@ -813,22 +820,13 @@ impl Span {
/// Furthermore, `entered` may be used when the span must be stored in some
/// other struct or be passed to a function while remaining entered.
///
- ///
///
- ///
- /// **Note**: The returned [`EnteredSpan`] guard does not
- /// implement `Send`. Dropping the guard will exit *this* span,
- /// and if the guard is sent to another thread and dropped there, that thread may
- /// never have entered this span. Thus, `EnteredSpan`s should not be sent
- /// between threads.
- ///
- ///
EnteredSpan guard does not implement Send.
+ /// Dropping the guard will exit this span, and if the guard is sent
+ /// to another thread and dropped there, that thread may never have entered
+ /// this span. Thus, EnteredSpans should not be sent between threads.
+ ///
///
/// [syntax]: https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html
///
@@ -1159,14 +1157,15 @@ impl Span {
/// }
/// ```
///
- ///
///
- /// Note: The fields associated with a span are part of its
- /// Metadata.
- /// The Metadata. describing a particular
- /// span is constructed statically when the span is created and cannot be extended later to
- /// add new fields. Therefore, you cannot record a value for a field that was not specified
- /// when the span was created:
Metadata.
+ /// The Metadata
+ /// describing a particular span is constructed statically when the span
+ /// is created and cannot be extended later to add new fields. Therefore,
+ /// you cannot record a value for a field that was not specified when the
+ /// span was created:
+ ///
///
/// ```
/// use tracing::{trace_span, field};