From 006b96c911ec2a6b2ab0f473dd309b99b5810af2 Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Thu, 16 Sep 2021 10:18:39 -0700 Subject: [PATCH] docs: remove divs from all notes/warnings (#1572) This branch removes the HTML `
` tags from the warning and note blocks in the documentation, because they're screwing up RustDoc rendering on docs.rs. We had done this previously on the `master` branch, but apparently it never made it to `v0.1.x`. This should fix #1571 once a new `tracing` version is published. --- tracing-core/src/dispatcher.rs | 55 +++++++------- tracing-core/src/span.rs | 4 +- tracing-subscriber/src/layer/context.rs | 96 ++++++++++++------------- tracing-subscriber/src/layer/mod.rs | 11 +-- tracing-subscriber/src/registry/mod.rs | 1 - tracing/src/dispatcher.rs | 4 +- tracing/src/field.rs | 1 - tracing/src/lib.rs | 20 +++--- tracing/src/span.rs | 33 +++------ 9 files changed, 97 insertions(+), 128 deletions(-) diff --git a/tracing-core/src/dispatcher.rs b/tracing-core/src/dispatcher.rs index d02eb0e790..61d5b0b73a 100644 --- a/tracing-core/src/dispatcher.rs +++ b/tracing-core/src/dispatcher.rs @@ -108,14 +108,13 @@ //! // `my_subscriber` is now the default //! ``` //! -//!
//! 
-//! Note:the thread-local scoped dispatcher
-//! (with_default) requires the
-//! Rust standard library. no_std users should use
-//! set_global_default
-//! instead.
-//!
+//! Note:the thread-local scoped dispatcher +//! (with_default) requires the +//! Rust standard library. no_std users should use +//! set_global_default +//! instead. +//! //! //! ## Accessing the Default Subscriber //! @@ -208,12 +207,11 @@ pub struct DefaultGuard(Option); /// The default dispatcher is used when creating a new [span] or /// [`Event`]. /// -///
/// 
-/// Note: This function required the Rust standard library.
-/// no_std users should use 
-/// set_global_default instead.
-///
+/// Note: This function required the Rust standard library. +/// no_std users should use +/// set_global_default instead. +/// /// /// [span]: ../span/index.html /// [`Subscriber`]: ../subscriber/trait.Subscriber.html @@ -233,12 +231,11 @@ pub fn with_default(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T { /// Sets the dispatch as the default dispatch for the duration of the lifetime /// of the returned DefaultGuard /// -///
/// 
-/// Note: This function required the Rust standard library.
-/// no_std users should use 
-/// set_global_default instead.
-///
+/// Note: This function required the Rust standard library. +/// no_std users should use +/// set_global_default instead. +/// /// /// [`set_global_default`]: ../fn.set_global_default.html #[cfg(feature = "std")] @@ -258,12 +255,11 @@ pub fn set_default(dispatcher: &Dispatch) -> DefaultGuard { /// Can only be set once; subsequent attempts to set the global default will fail. /// Returns `Err` if the global default has already been set. /// -/// -/// 
-/// 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.
+///
/// /// [span]: ../span/index.html /// [`Subscriber`]: ../subscriber/trait.Subscriber.html @@ -572,13 +568,14 @@ impl Dispatch { /// must as well. /// /// This calls the [`drop_span`] function on the [`Subscriber`] that this - /// `Dispatch` forwards to. + /// `Dispatch` forwards to. /// - /// 
-    /// Deprecated: The try_close
-    /// method is functionally identical, but returns true if the span is now closed.
-    /// It should be used instead of this method.
-    ///
+ /// 
+    ///     Deprecated: The 
+    ///     try_close method is functionally identical, but returns
+    ///     true if the span is now closed. It should be used
+    ///     instead of this method.
+    ///
/// /// [span ID]: ../span/struct.Id.html /// [`Subscriber`]: ../subscriber/trait.Subscriber.html diff --git a/tracing-core/src/span.rs b/tracing-core/src/span.rs index 49c1cb95d5..89db03ed4f 100644 --- a/tracing-core/src/span.rs +++ b/tracing-core/src/span.rs @@ -61,9 +61,9 @@ enum CurrentInner { impl Id { /// Constructs a new span ID from the given `u64`. /// - ///
/// 
-    /// Note: Span IDs must be greater than zero.
+ /// Note: Span IDs must be greater than zero. + /// /// /// # Panics /// - If the provided `u64` is 0. diff --git a/tracing-subscriber/src/layer/context.rs b/tracing-subscriber/src/layer/context.rs index a59e5faef3..a4dc508206 100644 --- a/tracing-subscriber/src/layer/context.rs +++ b/tracing-subscriber/src/layer/context.rs @@ -183,13 +183,13 @@ where /// }); /// ``` /// - ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// #[inline] pub fn event_span(&self, event: &Event<'_>) -> Option> where @@ -223,13 +223,13 @@ where /// If this returns `None`, then no span exists for that ID (either it has /// closed or the ID is invalid). /// - ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// /// /// [stored data]: ../registry/struct.SpanRef.html #[inline] @@ -248,13 +248,13 @@ where /// Returns `true` if an active span exists for the given `Id`. /// - ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// #[inline] pub fn exists(&self, id: &span::Id) -> bool where @@ -268,13 +268,13 @@ where /// /// If this returns `None`, then we are not currently within a span. /// - ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// /// /// [stored data]: ../registry/struct.SpanRef.html #[inline] @@ -343,13 +343,13 @@ where /// /// If this iterator is empty, then there are no spans in the current context. /// - ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// /// /// [stored data]: ../registry/struct.SpanRef.html #[deprecated( @@ -375,27 +375,20 @@ where /// current context, starting with the specified span and ending with the /// root of the trace tree and ending with the current span. /// - ///
- ///
ⓘNote
- ///
- ///
/// 
     /// Note: Compared to scope this
     /// returns the spans in reverse order (from leaf to root). Use
     /// Scope::from_root
     /// in case root-to-leaf ordering is desired.
-    ///
+ /// /// - ///
- ///
ⓘNote
- ///
- ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// /// /// [stored data]: ../registry/struct.SpanRef.html pub fn span_scope(&self, id: &span::Id) -> Option> @@ -409,21 +402,20 @@ where /// current context, starting with the parent span of the specified event, /// and ending with the root of the trace tree and ending with the current span. /// - ///
/// 
     /// Note: Compared to scope this
     /// returns the spans in reverse order (from leaf to root). Use
     /// Scope::from_root
     /// in case root-to-leaf ordering is desired.
-    ///
+ /// /// - ///
/// 
-    /// Note: This requires the wrapped subscriber to implement the
-    /// LookupSpan trait.
-    /// See the documentation on Context's
-    /// declaration for details.
-    ///
+ /// Note: This requires the wrapped subscriber to + /// implement the + /// LookupSpan trait. See the documentation on + /// Context's + /// declaration for details. + /// /// /// [stored data]: ../registry/struct.SpanRef.html pub fn event_scope(&self, event: &Event<'_>) -> Option> diff --git a/tracing-subscriber/src/layer/mod.rs b/tracing-subscriber/src/layer/mod.rs index f325436cbb..f3a87898e0 100644 --- a/tracing-subscriber/src/layer/mod.rs +++ b/tracing-subscriber/src/layer/mod.rs @@ -210,14 +210,13 @@ //! function pointer. In addition, when more control is required, the [`Filter`] //! trait may also be implemented for user-defined types. //! -//!
//! 
 //!     Warning: Currently, the 
 //!     Registry type defined in this crate is the only root
 //!     Subscriber capable of supporting Layers with
 //!     per-layer filters. In the future, new APIs will be added to allow other
 //!     root Subscribers to support per-layer filters.
-//!
+//! //! //! For example, to generate an HTTP access log based on spans with //! the `http_access` target, while logging other spans and events to @@ -483,7 +482,6 @@ where /// By default, this returns [`Interest::always()`] if [`self.enabled`] returns /// true, or [`Interest::never()`] if it returns false. /// - ///
/// 
     /// Note: This method (and 
     /// Layer::enabled) determine whether a span or event is
@@ -496,7 +494,7 @@ where
     /// on_enter,
     /// on_exit, and other notification
     /// methods.
-    ///
+ /// /// /// See [the trait-level documentation] for more information on filtering /// with `Layer`s. @@ -532,7 +530,6 @@ where /// By default, this always returns `true`, allowing the wrapped subscriber /// to choose to disable the span. /// - ///
/// 
     /// Note: This method (and 
     /// Layer::register_callsite) determine whether a span or event is
@@ -545,7 +542,7 @@ where
     /// on_enter,
     /// on_exit, and other notification
     /// methods.
-    ///
+ /// /// /// /// See [the trait-level documentation] for more information on filtering @@ -831,7 +828,6 @@ pub trait Filter { /// never enable a particular callsite, providing an implementation of this /// function is recommended. /// - ///
/// 
     /// 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.
     ///
- ///
/// /// This method is broadly similar to [`Subscriber::register_callsite`]; /// however, since the returned value represents only the interest of diff --git a/tracing-subscriber/src/registry/mod.rs b/tracing-subscriber/src/registry/mod.rs index 298dcb6e75..b292bf71f9 100644 --- a/tracing-subscriber/src/registry/mod.rs +++ b/tracing-subscriber/src/registry/mod.rs @@ -99,7 +99,6 @@ pub trait LookupSpan<'a> { /// Returns the [`SpanData`] for a given [`Id`], if it exists. /// - ///
/// 
     ///
     /// **Note**: users of the `LookupSpan` trait should
diff --git a/tracing/src/dispatcher.rs b/tracing/src/dispatcher.rs
index 0d4c8f9d90..8e760a3913 100644
--- a/tracing/src/dispatcher.rs
+++ b/tracing/src/dispatcher.rs
@@ -107,13 +107,13 @@
 //!
 //! // `my_subscriber` is now the default
 //! ```
-//! 

+//!
 //! 
 //! Note: The thread-local scoped dispatcher (with_default)
 //! requires the Rust standard library. no_std users should
 //! use set_global_default
 //! instead.
-//! 

+//!
//! //! ## Accessing the Default Subscriber //! diff --git a/tracing/src/field.rs b/tracing/src/field.rs index 55467ebd82..5e5e896801 100644 --- a/tracing/src/field.rs +++ b/tracing/src/field.rs @@ -5,7 +5,6 @@ use crate::Metadata; /// Trait implemented to allow a type to be used as a field key. /// -///
/// 
 ///
 /// **Note**: Although this is implemented for both the [`Field`] type
diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs
index b1ba431db5..826bedada0 100644
--- a/tracing/src/lib.rs
+++ b/tracing/src/lib.rs
@@ -584,12 +584,11 @@
 //! # }
 //! ```
 //!
-//! 

-//! 
-//! 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 collector will be used as the default in all threads for the
 //! remainder of the duration of the program, similar to setting the logger
@@ -860,12 +859,11 @@
 //! [`tracing-cloudwatch`]: https://crates.io/crates/tracing-cloudwatch
 //! [`clippy-tracing`]: https://crates.io/crates/clippy-tracing
 //!
-//! 

 //! 
-//! 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.
-//! 

+//!     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.
+//!
//! //! ## Crate Feature Flags //! diff --git a/tracing/src/span.rs b/tracing/src/span.rs index 0af9ac8214..543b70b8df 100644 --- a/tracing/src/span.rs +++ b/tracing/src/span.rs @@ -104,13 +104,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.
-//!
+//! 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. +//! //! //! ## Span Relationships //! @@ -839,22 +838,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.
-    ///
-    ///
- /// - /// **Warning**: in asynchronous code that uses [async/await syntax][syntax], - /// [`Span::entered`] should be used very carefully or avoided entirely. Holding - /// the drop guard returned by `Span::entered` across `.await` points will - /// result in incorrect traces. See the documentation for the - /// [`Span::enter`] method for details. + /// 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, EnteredSpans should not be sent between threads. + /// /// /// [syntax]: https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html /// @@ -1184,7 +1174,6 @@ impl Span { /// } /// ``` /// - ///
/// 
     ///
     /// **Note**: The fields associated with a span are part of its [`Metadata`].