Skip to content

Commit

Permalink
docs: remove divs from all notes/warnings (tokio-rs#1572)
Browse files Browse the repository at this point in the history 
This branch removes the HTML `<div>` 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 tokio-rs#1571 once a new `tracing` version is published.
  • Loading branch information
@hawkw @kaffarell
hawkw authored and kaffarell committed May 22, 2024
1 parent 76355a6 commit 006b96c
Show file tree
Hide file tree
Showing 9 changed files with 97 additions and 128 deletions.
55 changes: 26 additions & 29 deletions tracing-core/src/dispatcher.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,14 +108,13 @@
//! // `my_subscriber` is now the default
//! ```
//!
//! <div class="example-wrap" style="display:inline-block">
//! <pre class="ignore" style="white-space:normal;font:inherit;">
//! <strong>Note</strong>:the thread-local scoped dispatcher
//! (<a href="#fn.with_default"><code>with_default</code></a>) requires the
//! Rust standard library. <code>no_std</code> users should use
//! <a href="#fn.set_global_default"><code>set_global_default</code></a>
//! instead.
//! </pre></div>
//! <strong>Note</strong>:the thread-local scoped dispatcher
//! (<a href="#fn.with_default"><code>with_default</code></a>) requires the
//! Rust standard library. <code>no_std</code> users should use
//! <a href="#fn.set_global_default"><code>set_global_default</code></a>
//! instead.
//! </pre>
//!
//! ## Accessing the Default Subscriber
//!
Expand Down Expand Up @@ -208,12 +207,11 @@ pub struct DefaultGuard(Option<Dispatch>);
/// The default dispatcher is used when creating a new [span] or
/// [`Event`].
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This function required the Rust standard library.
/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
/// <code>set_global_default</code></a> instead.
/// </pre></div>
/// <strong>Note</strong>: This function required the Rust standard library.
/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
/// <code>set_global_default</code></a> instead.
/// </pre>
///
/// [span]: ../span/index.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
Expand All @@ -233,12 +231,11 @@ pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T {
/// Sets the dispatch as the default dispatch for the duration of the lifetime
/// of the returned DefaultGuard
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This function required the Rust standard library.
/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
/// <code>set_global_default</code></a> instead.
/// </pre></div>
/// <strong>Note</strong>: This function required the Rust standard library.
/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
/// <code>set_global_default</code></a> instead.
/// </pre>
///
/// [`set_global_default`]: ../fn.set_global_default.html
#[cfg(feature = "std")]
Expand All @@ -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.
///
///
/// </div><div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
/// <strong>Warning</strong>: In general, libraries should <em>not</em> call
/// <code>set_global_default()</code>! Doing so will cause conflicts when
/// executables that depend on the library try to set the default later.
/// </pre></div>
/// <pre class="compile_fail" style="white-space:normal;font:inherit;">
/// <strong>Warning</strong>: In general, libraries should <em>not</em> call
/// <code>set_global_default()</code>! Doing so will cause conflicts when
/// executables that depend on the library try to set the default later.
/// </pre>
///
/// [span]: ../span/index.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
Expand Down Expand Up @@ -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.
///
/// <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
/// <strong>Deprecated</strong>: The <a href="#method.try_close"><code>try_close</code></a>
/// method is functionally identical, but returns <code>true</code> if the span is now closed.
/// It should be used instead of this method.
/// </pre></div>
/// <pre class="compile_fail" style="white-space:normal;font:inherit;">
/// <strong>Deprecated</strong>: The <a href="#method.try_close"><code>
/// try_close</code></a> method is functionally identical, but returns
/// <code>true</code> if the span is now closed. It should be used
/// instead of this method.
/// </pre>
///
/// [span ID]: ../span/struct.Id.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
Expand Down
4 changes: 2 additions & 2 deletions tracing-core/src/span.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,9 @@ enum CurrentInner {
impl Id {
/// Constructs a new span ID from the given `u64`.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: Span IDs must be greater than zero.</pre></div>
/// <strong>Note</strong>: Span IDs must be greater than zero.
/// </pre>
///
/// # Panics
/// - If the provided `u64` is 0.
Expand Down
96 changes: 44 additions & 52 deletions tracing-subscriber/src/layer/context.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -183,13 +183,13 @@ where
/// });
/// ```
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
#[inline]
pub fn event_span(&self, event: &Event<'_>) -> Option<SpanRef<'_, S>>
where
Expand Down Expand Up @@ -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).
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
///
/// [stored data]: ../registry/struct.SpanRef.html
#[inline]
Expand All @@ -248,13 +248,13 @@ where

/// Returns `true` if an active span exists for the given `Id`.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
#[inline]
pub fn exists(&self, id: &span::Id) -> bool
where
Expand All @@ -268,13 +268,13 @@ where
///
/// If this returns `None`, then we are not currently within a span.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
///
/// [stored data]: ../registry/struct.SpanRef.html
#[inline]
Expand Down Expand Up @@ -343,13 +343,13 @@ where
///
/// If this iterator is empty, then there are no spans in the current context.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
///
/// [stored data]: ../registry/struct.SpanRef.html
#[deprecated(
Expand All @@ -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.
///
/// <div class="information">
/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div>
/// </div>
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: Compared to <a href="#method.scope"><code>scope</code></a> this
/// returns the spans in reverse order (from leaf to root). Use
/// <a href="../registry/struct.Scope.html#method.from_root"><code>Scope::from_root</code></a>
/// in case root-to-leaf ordering is desired.
/// </pre></div>
/// </pre>
///
/// <div class="information">
/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div>
/// </div>
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
///
/// [stored data]: ../registry/struct.SpanRef.html
pub fn span_scope(&self, id: &span::Id) -> Option<registry::Scope<'_, S>>
Expand All @@ -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.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: Compared to <a href="#method.scope"><code>scope</code></a> this
/// returns the spans in reverse order (from leaf to root). Use
/// <a href="../registry/struct.Scope.html#method.from_root"><code>Scope::from_root</code></a>
/// in case root-to-leaf ordering is desired.
/// </pre></div>
/// </pre>
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This requires the wrapped subscriber to implement the
/// <a href="../registry/trait.LookupSpan.html"><code>LookupSpan</code></a> trait.
/// See the documentation on <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre></div>
/// <strong>Note</strong>: This requires the wrapped subscriber to
/// implement the <a href="../registry/trait.LookupSpan.html"><code>
/// LookupSpan</code></a> trait. See the documentation on
/// <a href="./struct.Context.html"><code>Context</code>'s
/// declaration</a> for details.
/// </pre>
///
/// [stored data]: ../registry/struct.SpanRef.html
pub fn event_scope(&self, event: &Event<'_>) -> Option<registry::Scope<'_, S>>
Expand Down
11 changes: 3 additions & 8 deletions tracing-subscriber/src/layer/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,14 +210,13 @@
//! 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">
//! <code>Registry</code></a> type defined in this crate is the only root
//! <code>Subscriber</code> capable of supporting <code>Layer</code>s with
//! per-layer filters. In the future, new APIs will be added to allow other
//! root <code>Subscriber</code>s to support per-layer filters.
//! </pre></div>
//! </pre>
//!
//! For example, to generate an HTTP access log based on spans with
//! the `http_access` target, while logging other spans and events to
Expand Down Expand Up @@ -483,7 +482,6 @@ where
/// By default, this returns [`Interest::always()`] if [`self.enabled`] returns
/// true, or [`Interest::never()`] if it returns false.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This method (and <a href="#method.enabled">
/// <code>Layer::enabled</code></a>) determine whether a span or event is
Expand All @@ -496,7 +494,7 @@ where
/// <a href="#method.on_enter"><code>on_enter</code></a>,
/// <a href="#method.on_exit"><code>on_exit</code></a>, and other notification
/// methods.
/// </pre></div>
/// </pre>
///
/// See [the trait-level documentation] for more information on filtering
/// with `Layer`s.
Expand Down Expand Up @@ -532,7 +530,6 @@ where
/// By default, this always returns `true`, allowing the wrapped subscriber
/// to choose to disable the span.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This method (and <a href="#method.register_callsite">
/// <code>Layer::register_callsite</code></a>) determine whether a span or event is
Expand All @@ -545,7 +542,7 @@ where
/// <a href="#method.on_enter"><code>on_enter</code></a>,
/// <a href="#method.on_exit"><code>on_exit</code></a>, and other notification
/// methods.
/// </pre></div>
/// </pre>
///
///
/// See [the trait-level documentation] for more information on filtering
Expand Down Expand Up @@ -831,7 +828,6 @@ pub trait Filter<S> {
/// never enable a particular callsite, providing an implementation of this
/// function is recommended.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: If a <code>Filter</code> will perform
/// <em>dynamic filtering</em> that depends on the current context in which
Expand All @@ -842,7 +838,6 @@ pub trait Filter<S> {
/// <code>enabled</code> method may not be called when a particular instance
/// of that span or event is recorded.
/// </pre>
/// </div>
///
/// This method is broadly similar to [`Subscriber::register_callsite`];
/// however, since the returned value represents only the interest of
Expand Down
1 change: 0 additions & 1 deletion tracing-subscriber/src/registry/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,6 @@ pub trait LookupSpan<'a> {

/// Returns the [`SpanData`] for a given [`Id`], if it exists.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
///
/// **Note**: users of the `LookupSpan` trait should
Expand Down
4 changes: 2 additions & 2 deletions tracing/src/dispatcher.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,13 +107,13 @@
//!
//! // `my_subscriber` is now the default
//! ```
//! <div class="example-wrap" style="display:inline-block">
//!
//! <pre class="ignore" style="white-space:normal;font:inherit;">
//! <strong>Note</strong>: The thread-local scoped dispatcher (<code>with_default</code>)
//! requires the Rust standard library. <code>no_std</code> users should
//! use <a href="fn.set_global_default.html"><code>set_global_default</code></a>
//! instead.
//! </pre></div>
//! </pre>
//!
//! ## Accessing the Default Subscriber
//!
Expand Down
1 change: 0 additions & 1 deletion tracing/src/field.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ use crate::Metadata;

/// Trait implemented to allow a type to be used as a field key.
///
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
///
/// **Note**: Although this is implemented for both the [`Field`] type
Expand Down
Loading

0 comments on commit 006b96c

Please sign in to comment.