docs: better docs on async usage; fancy warning formatting, etc #769

hawkw · 2020-06-26T22:08:39Z

This branch makes the following changes:

Add a new section to the Span::enter docs that explains why
it should be avoided in async code, and suggests alternatives.
Add links to the new section elsewhere.
Add new formatting for "Notes" and "Warnings" in the documentation,
by (mis?)using existing styles from the RustDoc stylesheet.
Fixed a handful of inaccuracies or outdated statements I noticed
while making other changes.

Fixes #667

Signed-off-by: Eliza Weisman eliza@buoyant.io

Fixes #667 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

sorry david i just really hate this (and the terrible line wrapping that results from it) Signed-off-by: Eliza Weisman <eliza@buoyant.io>

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

we can't add it as adev dependecy, since this creates a circular dependency Signed-off-by: Eliza Weisman <eliza@buoyant.io>

README.md

Co-authored-by: David Barsky <me@davidbarsky.com>

README.md

Co-authored-by: David Barsky <me@davidbarsky.com>

yaahc

--

yaahc · 2020-06-29T18:56:38Z

tracing-core/src/dispatcher.rs

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


the newline after this is showing up in the preview

yaahc · 2020-06-29T18:58:45Z

tracing-core/src/dispatcher.rs

+///     <div class="tooltip compile_fail" style="">&#x26a0; &#xfe0f;<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


the ! here reads a little oddly

That's not specific to the new HTML formatting, I'm pretty sure rustdoc would look the same for any instance of

`some text`!

I figured as much, in this one case I was just saying I thought it looked funny rather than it looks broken.

yaahc · 2020-06-29T18:59:43Z

tracing-core/src/dispatcher.rs

+    /// <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>


CSS after this entry gets messed up somehow

yaahc · 2020-06-29T19:00:46Z

tracing-core/src/field.rs

+/// <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 `


extra backtick

Suggested change

/// available when the Rust standard library is present, as it requires the `

/// available when the Rust standard library is present, as it requires the

yaahc · 2020-06-29T19:01:50Z

tracing-core/src/field.rs

@@ -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">


something fucky is going on here...

yaahc · 2020-06-29T19:03:03Z

tracing-core/src/field.rs

    /// of those callsites are not equivalent.
+    /// </pre>
+    /// </div>


similar formatting bleedthrough

yaahc · 2020-06-29T19:04:34Z

tracing-core/src/span.rs

+    /// <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>


formatting effects need to be scoped here as well

yaahc · 2020-06-29T19:07:35Z

tracing-subscriber/src/layer.rs

-    /// **Note:** This method (and [`Layer::enabled`]) determine whether a
-    /// span or event is globally enabled, _not_ whether the individual layer
-    /// will be notified about that span or event. This is intended to be used
+    /// <div class="information">


This one sploded

yaahc · 2020-06-29T19:09:00Z

tracing-subscriber/src/registry/mod.rs

-    /// **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
+    /// <div class="information">


Gonna stop on this one, These all seem to be the same issue, I'm assuming once you fix it the rest will be minor formatting issues and it will be easier to review them without the sploded formatting everywhere distracting me.

## Motivation PR #769 was merged with some incorrect docs formatting due to incorrect HTML that resulted from overzealous find-and-replace misuse. See #769 (review) ## Solution This PR un-splodes it. Signed-off-by: Eliza Weisman <eliza@buoyant.io>

@rkuhn

Changed: - **parking_lot**: Updated the optional `parking_lot` dependency to accept the latest `parking_lot` version (#774) Fixed - **fmt**: Fixed events with explicitly overridden parent spans being formatted as though they were children of the current span (#767) Added - **fmt**: Added the option to print synthesized events when spans are created, entered, exited, and closed, including span durations (#761) - Documentation clarification and improvement (#762, #769) Thanks to @rkuhn, @greenwoodcm, and @Ralith for contributing to this release! Signed-off-by: Eliza Weisman <eliza@buoyant.io>

@rkuhn

Changed: - **parking_lot**: Updated the optional `parking_lot` dependency to accept the latest `parking_lot` version (#774) Fixed - **fmt**: Fixed events with explicitly overridden parent spans being formatted as though they were children of the current span (#767) Added - **fmt**: Added the option to print synthesized events when spans are created, entered, exited, and closed, including span durations (#761) - Documentation clarification and improvement (#762, #769) Thanks to @rkuhn, @greenwoodcm, and @Ralith for contributing to this release! Signed-off-by: Eliza Weisman <eliza@buoyant.io>

@rkuhn

### Changed - **parking_lot**: Updated the optional `parking_lot` dependency to accept the latest `parking_lot` version (#774) ### Fixed - **fmt**: Fixed events with explicitly overridden parent spans being formatted as though they were children of the current span (#767) ### Added - **fmt**: Added the option to print synthesized events when spans are created, entered, exited, and closed, including span durations (#761) - Documentation clarification and improvement (#762, #769) Thanks to @rkuhn, @greenwoodcm, and @Ralith for contributing to this release! Signed-off-by: Eliza Weisman <eliza@buoyant.io>

@bkchr

Changed - Replaced use of `inner_local_macros` with `$crate::` (#729) Added - `must_use` warning to guards returned by `dispatcher::set_default` (#686) - `fmt::Debug` impl to `dyn Value`s (#696) - Functions to convert between `span::Id` and `NonZeroU64` (#770) - More obvious warnings in documentation (#769) Fixed - Compiler error when `tracing-core/std` feature is enabled but `tracing/std` is not (#760) - Clippy warning on vtable address comparison in `callsite::Identifier` (#749) - Documentation formatting issues (#715, #771) Thanks to @bkchr, @majecty, @taiki-e, @nagisa, and @nqvz for contributing to this release!

@bkchr

### Changed - Replaced use of `inner_local_macros` with `$crate::` (#729) ### Added - `must_use` warning to guards returned by `dispatcher::set_default` (#686) - `fmt::Debug` impl to `dyn Value`s (#696) - Functions to convert between `span::Id` and `NonZeroU64` (#770) - More obvious warnings in documentation (#769) ### Fixed - Compiler error when `tracing-core/std` feature is enabled but `tracing/std` is not (#760) - Clippy warning on vtable address comparison in `callsite::Identifier` (#749) - Documentation formatting issues (#715, #771) Thanks to @bkchr, @majecty, @taiki-e, @nagisa, and @nvzqz for contributing to this release!

@nagisa

Added - **attributes**: Support for arbitrary expressions as fields in `#[instrument]` (#672) - **attributes**: `#[instrument]` now emits a compiler warning when ignoring unrecognized input (#672, #786) - Improved documentation on using `tracing` in async code (#769) Changed - Updated `tracing-core` dependency to 0.1.11 Fixed - **macros**: Excessive monomorphization in macros, which could lead to longer compilation times (#787) - **log**: Compiler warnings in macros when `log` or `log-always` features are enabled (#753) - Compiler error when `tracing-core/std` feature is enabled but `tracing/std` is not (#760) Thanks to @nagisa for contributing to this release!

@nagisa

### Added - **attributes**: Support for arbitrary expressions as fields in `#[instrument]` (#672) - **attributes**: `#[instrument]` now emits a compiler warning when ignoring unrecognized input (#672, #786) - Improved documentation on using `tracing` in async code (#769) ### Changed - Updated `tracing-core` dependency to 0.1.11 ### Fixed - **macros**: Excessive monomorphization in macros, which could lead to longer compilation times (#787) - **log**: Compiler warnings in macros when `log` or `log-always` features are enabled (#753) - Compiler error when `tracing-core/std` feature is enabled but `tracing/std` is not (#760) Thanks to @nagisa, and everyone who contributed to the new `tracing-core` and `tracing-attributes` versions, for contributing to this release!

hawkw added 5 commits June 26, 2020 11:11

docs: clarify README usage section

0a2e6e9

Fixes #667 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

docs: fix @davidbarsky's awful long markdown links

42d9d55

sorry david i just really hate this (and the terrible line wrapping that results from it) Signed-off-by: Eliza Weisman <eliza@buoyant.io>

docs: improve docs for Span::enter in async

162f11a

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

docs: (unnecessarily) fancy format for warnings

8155ed5

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

docs: apply fancy formatting to all notes/warnings

a4ce372

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

hawkw added kind/docs crate/subscriber Related to the `tracing-subscriber` crate crate/core Related to the `tracing-core` crate crate/tracing Related to the `tracing` crate labels Jun 26, 2020

hawkw requested review from yaahc, davidbarsky and LucioFranco June 26, 2020 22:08

hawkw requested a review from a team as a code owner June 26, 2020 22:08

hawkw self-assigned this Jun 26, 2020

hawkw added 2 commits June 26, 2020 16:21

add U+FE0E MAGICAL DONT BE AN EMOJI CHARACTER

75cd95a

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

ignore tracing-futures examples

d87ac2c

we can't add it as adev dependecy, since this creates a circular dependency Signed-off-by: Eliza Weisman <eliza@buoyant.io>

davidbarsky approved these changes Jun 27, 2020

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

Apply suggestions from code review

687f3fc

Co-authored-by: David Barsky <me@davidbarsky.com>

davidbarsky reviewed Jun 27, 2020

View reviewed changes

README.md Outdated Show resolved Hide resolved

Update README.md

435504d

Co-authored-by: David Barsky <me@davidbarsky.com>

LucioFranco approved these changes Jun 29, 2020

View reviewed changes

hawkw merged commit ef8efaa into master Jun 29, 2020

hawkw deleted the eliza/async-enter-warning branch June 29, 2020 19:01

yaahc reviewed Jun 29, 2020

View reviewed changes

hawkw mentioned this pull request Jun 29, 2020

docs: fix "sploded" formatting #771

Merged

hawkw mentioned this pull request Jul 1, 2020

subscriber: prepare to release 0.2.7 (July 1, 2020) #775

Merged

hawkw mentioned this pull request Jul 8, 2020

core: prepare to release 0.1.11 #788

Merged

hawkw mentioned this pull request Jul 8, 2020

tracing: prepare to release 0.1.16 #789

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: better docs on async usage; fancy warning formatting, etc #769

docs: better docs on async usage; fancy warning formatting, etc #769

hawkw commented Jun 26, 2020

yaahc left a comment

yaahc Jun 29, 2020

yaahc Jun 29, 2020

hawkw Jun 29, 2020 •

edited

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

yaahc Jun 29, 2020

	/// available when the Rust standard library is present, as it requires the `
	/// available when the Rust standard library is present, as it requires the

docs: better docs on async usage; fancy warning formatting, etc #769

docs: better docs on async usage; fancy warning formatting, etc #769

Conversation

hawkw commented Jun 26, 2020

yaahc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hawkw Jun 29, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hawkw Jun 29, 2020 •

edited