Skip to content
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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: document span.in_scope() at top-level #1344

Merged
merged 2 commits into from
Apr 30, 2021
Merged

docs: document span.in_scope() at top-level #1344

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f93f0e
docs: document span.in_scope() at top-level
Fishrock123 Apr 1, 2021
50cc4b3
fix types in doctest
hawkw Apr 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
19 changes: 19 additions & 0 deletions tracing/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,25 @@
//! # fn main() {}
//! ```
//!
//! For functions which don't have built-in tracing support and can't have
//! the `#[instrument]` attribute applied (such as from an external crate,
//! the [`Span` struct][`Span`] has a [`in_scope()` method][`in_scope`]
//! which can be used to easily wrap synchonous code in a span.
//!
//! For example:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

take it or leave it: maybe we ought to also have an example showing that in_scope can be called multiple times on the same span, like

let span = tracing::info_span!(...);

let something = span.in_scope(|| some_function());
let other_thing = span.in_scope(|| other_function());

or whatever?

On the other hand, maybe this is better left in the function-level docs for in_scope?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should leave that in the in_scope() docs. Even just mentioning it here would probably be enough, but I think the serde example will be quite nice.

//! ```rust
//! use tracing::info_span;
//!
//! # fn doc() -> Result<(), ()> {
//! # mod serde_json {
//! # pub(crate) fn from_slice(buf: &[u8]) -> Result<(), ()> { Ok(()) }
//! # }
//! # let buf: [u8; 0] = [];
//! let json = info_span!("json.parse").in_scope(|| serde_json::from_slice(&buf))?;
Fishrock123 marked this conversation as resolved.
Show resolved Hide resolved
hawkw marked this conversation as resolved.
Show resolved Hide resolved
//! # let _ = json; // suppress unused variable warning
//! # Ok(())
//! # }
//! ```
//!
//! You can find more examples showing how to use this crate [here][examples].
//!
Expand Down