From f12176e53703b7b66f04fb9c3b3d749e7b02b2fb 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/metadata.rs | 16 ++--- 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 | 3 +- tracing/src/dispatcher.rs | 4 +- tracing/src/field.rs | 1 - tracing/src/lib.rs | 34 ++++----- tracing/src/span.rs | 63 ++++++++-------- 10 files changed, 131 insertions(+), 156 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/metadata.rs b/tracing-core/src/metadata.rs index 5b9b5584f7..6a9f6de5fc 100644 --- a/tracing-core/src/metadata.rs +++ b/tracing-core/src/metadata.rs @@ -35,15 +35,15 @@ use crate::stdlib::{ /// _significantly_ lower than that of creating the actual span. Therefore, /// filtering is based on metadata, rather than on the constructed span. /// -///
/// 
-/// Note: Although instances of Metadata cannot
-/// be compared directly, they provide a method 
-/// id, returning an opaque 
-/// callsite identifier  which uniquely identifies the callsite where the metadata
-/// originated. This can be used to determine if two Metadata correspond to
-/// the same callsite.
-///
+/// Note: Although instances of Metadata +/// cannot be compared directly, they provide a method +/// id, returning +/// an opaque callsite +/// identifierwhich uniquely identifies the callsite where the metadata +/// originated. This can be used to determine if two Metadata +/// correspond to the same callsite. +/// /// /// [span]: ../span/index.html /// [event]: ../event/index.html diff --git a/tracing-core/src/span.rs b/tracing-core/src/span.rs index b69d66c895..87e1b92533 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 9951c50d30..ad0d8e0964 100644 --- a/tracing-subscriber/src/registry/mod.rs +++ b/tracing-subscriber/src/registry/mod.rs @@ -98,14 +98,13 @@ pub trait LookupSpan<'a> { /// Returns the [`SpanData`] for a given `Id`, if it exists. /// - ///
/// 
     /// 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.
-    ///
+ /// /// /// [`SpanData`]: trait.SpanData.html fn span_data(&'a self, id: &Id) -> Option; 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 96416638c0..5525ab9b06 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 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.
-//!
+//! //! //! ## Events //! @@ -576,12 +576,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 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.
-//!
+//! 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 //! @@ -800,14 +798,10 @@ //! tracing = { version = "0.1.27", default-features = false } //! ``` //! -//!
-//!
ⓘNote
-//!
-//!
//! 
-//! Note: tracing's no_std support
-//! requires liballoc.
-//!
+//! Note: 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.
-//!
+//! 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 //! @@ -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.
-    ///
-    ///
- /// - /// **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 /// @@ -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:
+ /// 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: + /// /// /// ``` /// use tracing::{trace_span, field};