-
Notifications
You must be signed in to change notification settings - Fork 672
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: better docs on async usage; fancy warning formatting, etc #769
Changes from all commits
0a2e6e9
42d9d55
162f11a
8155ed5
a4ce372
75cd95a
d87ac2c
687f3fc
435504d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -108,9 +108,16 @@ | |
//! // `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`] | ||
//! <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>: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"><code>set_global_default</code></a> | ||
//! instead. | ||
//! </pre></div> | ||
//! | ||
//! Finally, `tokio` users should note that versions of `tokio` >= 0.1.22 | ||
//! support an `experimental-tracing` feature flag. When this flag is enabled, | ||
|
@@ -204,8 +211,15 @@ pub struct DefaultGuard(Option<Dispatch>); | |
/// The default dispatcher is used when creating a new [span] or | ||
/// [`Event`]. | ||
/// | ||
/// **Note**: This function requires the Rust standard library. `no_std` users | ||
/// should use [`set_global_default`] instead. | ||
/// <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 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> | ||
/// | ||
/// [span]: ../span/index.html | ||
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html | ||
|
@@ -225,8 +239,15 @@ 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 | ||
/// | ||
/// **Note**: This function required the Rust standard library. `no_std` users | ||
/// should use [`set_global_default`] instead. | ||
/// <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 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> | ||
/// | ||
/// [`set_global_default`]: ../fn.set_global_default.html | ||
#[cfg(feature = "std")] | ||
|
@@ -246,8 +267,14 @@ 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. | ||
/// | ||
/// Note: Libraries should *NOT* call `set_global_default()`! That will cause conflicts when | ||
/// executables try to set them later. | ||
/// | ||
/// <div class="information"> | ||
/// <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> | ||
/// </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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That's not specific to the new HTML formatting, I'm pretty sure rustdoc would look the same for any instance of `some text`! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I figured as much, in this one case I was just saying I thought it looked funny rather than it looks broken. |
||
/// executables that depend on the library try to set the default later. | ||
/// </pre></div> | ||
/// | ||
/// [span]: ../span/index.html | ||
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html | ||
|
@@ -525,8 +552,14 @@ impl Dispatch { | |
/// This calls the [`drop_span`] function on the [`Subscriber`] that this | ||
/// `Dispatch` forwards to. | ||
/// | ||
/// **Note:** the [`try_close`] function is functionally identical, but | ||
/// returns `true` if the span is now closed. | ||
/// <div class="information"> | ||
/// <div class="tooltip compile_fail" style="">⚠ ️<span class="tooltiptext">Warning</span></div> | ||
/// </div> | ||
/// <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> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
/// | ||
/// [span ID]: ../span/struct.Id.html | ||
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -169,8 +169,15 @@ pub struct Iter { | |
/// `examples/counters.rs`, which demonstrates a very simple metrics system | ||
/// implemented using `tracing`. | ||
/// | ||
/// **Note:** the `record_error` trait method is only available when the Rust | ||
/// standard library is present, as it requires the `std::error::Error` trait. | ||
/// <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>: The <code>record_error</code> trait method is only | ||
/// available when the Rust standard library is present, as it requires the ` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
/// <code>std::error::Error</code> trait. | ||
/// </pre></div> | ||
/// | ||
/// [`Value`]: trait.Value.html | ||
/// [recorded]: trait.Value.html#method.record | ||
|
@@ -202,8 +209,15 @@ pub trait Visit { | |
|
||
/// Records a type implementing `Error`. | ||
/// | ||
/// **Note**: this is only enabled when the Rust standard library is | ||
/// <div class="information"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> | ||
/// </div> | ||
/// <div class="example-wrap" style="display:inline-block"> | ||
/// <div class="example-wrap" style="display:inline-block"> | ||
/// <pre class="ignore" style="white-space:normal;font:inherit;"> | ||
/// <strong>Note</strong>: This is only enabled when the Rust standard library is | ||
/// present. | ||
/// </pre> | ||
#[cfg(feature = "std")] | ||
#[cfg_attr(docsrs, doc(cfg(feature = "std")))] | ||
fn record_error(&mut self, field: &Field, value: &(dyn std::error::Error + 'static)) { | ||
|
@@ -604,11 +618,20 @@ impl FieldSet { | |
|
||
/// Returns `true` if `self` contains the given `field`. | ||
/// | ||
/// **Note**: If `field` shares a name with a field in this `FieldSet`, but | ||
/// was created by a `FieldSet` with a different callsite, this `FieldSet` | ||
/// does _not_ contain it. This is so that if two separate span callsites | ||
/// define a field named "foo", the `Field` corresponding to "foo" for each | ||
/// <div class="information"> | ||
/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> | ||
/// </div> | ||
/// <div class="example-wrap" style="display:inline-block"> | ||
/// <div class="example-wrap" style="display:inline-block"> | ||
/// <pre class="ignore" style="white-space:normal;font:inherit;"> | ||
/// <strong>Note</strong>: If <code>field</code> shares a name with a field | ||
/// in this <code>FieldSet</code>, but was created by a <code>FieldSet</code> | ||
/// with a different callsite, this <code>FieldSet</code> does <em>not</em> | ||
/// contain it. This is so that if two separate span callsites define a field | ||
/// named "foo", the <code>Field</code> corresponding to "foo" for each | ||
/// of those callsites are not equivalent. | ||
/// </pre> | ||
/// </div> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
pub fn contains(&self, field: &Field) -> bool { | ||
field.callsite() == self.callsite() && field.i <= self.len() | ||
} | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -60,7 +60,13 @@ enum CurrentInner { | |
impl Id { | ||
/// Constructs a new span ID from the given `u64`. | ||
/// | ||
/// **Note**: Span IDs must be greater than zero. | ||
/// <div class="information"> | ||
/// <div class="tooltip ignore" style="">ⓘ<span class="tooltiptext">Note</span></div> | ||
/// </div> | ||
/// <div class="example-wrap" style="display:inline-block"> | ||
/// <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> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
/// | ||
/// # Panics | ||
/// - If the provided `u64` is 0 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the newline after this is showing up in the preview