From 848ee2d1576a7ef82d2c737dd0325df9c153256d Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Fri, 30 Apr 2021 09:53:00 -0700 Subject: [PATCH] docs: document span.in_scope() at top-level (#1344) ## Motivation `span.in_scope()` had a link def in the main tracing docs which was unused, this function is quite handy to know about and I almost re-implemented something similar to it. I almost reimplemented this as a macro. ## Solution Document it at top-level! Co-authored-by: Eliza Weisman --- tracing/src/lib.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs index 5500f21493..fb02eca2eb 100644 --- a/tracing/src/lib.rs +++ b/tracing/src/lib.rs @@ -173,6 +173,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: +//! ```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))?; +//! # let _ = json; // suppress unused variable warning +//! # Ok(()) +//! # } +//! ``` //! //! You can find more examples showing how to use this crate [here][examples]. //!