From e528e4adbd3577c47467e25c0bd404750bc57038 Mon Sep 17 00:00:00 2001
From: Eliza Weisman <eliza@buoyant.io>
Date: Sun, 21 Nov 2021 12:20:18 -0800
Subject: [PATCH] docs: remove `#[macro_use] extern crate` (#1737)

Some of the examples still include `#[macro_use] extern crate`
statements for importing macros from `tracing` or `tracing-core`. On a
recent nightly, this results in import conflicts with the implicit
import of the documented crate in doctests:
https://github.com/tokio-rs/tracing/runs/4279736243?check_suite_focus=true

This commit removes all the `extern crate` statements from doctests. Our
MSRV is new enough that `extern crate` is not required on any of the Rust
versions we support.

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
---
 tracing-core/src/lib.rs |  7 ++-----
 tracing/src/macros.rs   |  4 +---
 tracing/src/span.rs     | 27 +++++++++------------------
 3 files changed, 12 insertions(+), 26 deletions(-)

diff --git a/tracing-core/src/lib.rs b/tracing-core/src/lib.rs
index 9bf8f363ae..14d0f0854e 100644
--- a/tracing-core/src/lib.rs
+++ b/tracing-core/src/lib.rs
@@ -124,9 +124,7 @@ extern crate alloc;
 ///
 /// For example:
 /// ```rust
-/// # #[macro_use]
-/// # extern crate tracing_core;
-/// use tracing_core::callsite;
+/// use tracing_core::{callsite, identify_callsite};
 /// # use tracing_core::{Metadata, subscriber::Interest};
 /// # fn main() {
 /// pub struct MyCallsite {
@@ -160,9 +158,8 @@ macro_rules! identify_callsite {
 ///
 /// /// For example:
 /// ```rust
-/// # #[macro_use]
-/// # extern crate tracing_core;
 /// # use tracing_core::{callsite::Callsite, subscriber::Interest};
+/// use tracing_core::metadata;
 /// use tracing_core::metadata::{Kind, Level, Metadata};
 /// # fn main() {
 /// # pub struct MyCallsite { }
diff --git a/tracing/src/macros.rs b/tracing/src/macros.rs
index 2cffa3830f..af91eeca93 100644
--- a/tracing/src/macros.rs
+++ b/tracing/src/macros.rs
@@ -575,9 +575,7 @@ macro_rules! error_span {
 // ///
 // /// For example, the following does not compile:
 // /// ```rust,compile_fail
-// /// # #[macro_use]
-// /// # extern crate tracing;
-// /// # use tracing::Level;
+// /// # use tracing::{Level, event};
 // /// # fn main() {
 // /// event!(Level::INFO, foo = 5, bad_field, bar = "hello")
 // /// #}
diff --git a/tracing/src/span.rs b/tracing/src/span.rs
index 32c78959e6..e9e232703f 100644
--- a/tracing/src/span.rs
+++ b/tracing/src/span.rs
@@ -136,8 +136,7 @@
 //! as long as the longest-executing span in its subtree.
 //!
 //! ```
-//! # #[macro_use] extern crate tracing;
-//! # use tracing::Level;
+//! # use tracing::{Level, span};
 //! // this span is considered the "root" of a new trace tree:
 //! span!(Level::INFO, "root").in_scope(|| {
 //!     // since we are now inside "root", this span is considered a child
@@ -157,8 +156,7 @@
 //! the `span!` macro. For example:
 //!
 //! ```rust
-//! # #[macro_use] extern crate tracing;
-//! # use tracing::Level;
+//! # use tracing::{Level, span};
 //! // Create, but do not enter, a span called "foo".
 //! let foo = span!(Level::INFO, "foo");
 //!
@@ -200,8 +198,6 @@
 //! _closed_. Consider, for example, a future which has an associated
 //! span and enters that span every time it is polled:
 //! ```rust
-//! # extern crate tracing;
-//! # extern crate futures;
 //! # use futures::{Future, Poll, Async};
 //! struct MyFuture {
 //!    // data
@@ -241,8 +237,7 @@
 //! that handle "closes" the span, since the capacity to enter it no longer
 //! exists. For example:
 //! ```
-//! # #[macro_use] extern crate tracing;
-//! # use tracing::Level;
+//! # use tracing::{Level, span};
 //! {
 //!     span!(Level::TRACE, "my_span").in_scope(|| {
 //!         // perform some work in the context of `my_span`...
@@ -275,8 +270,7 @@
 //! construct one span and perform the entire loop inside of that span, like:
 //!
 //! ```rust
-//! # #[macro_use] extern crate tracing;
-//! # use tracing::Level;
+//! # use tracing::{Level, span};
 //! # let n = 1;
 //! let span = span!(Level::TRACE, "my_loop");
 //! let _enter = span.enter();
@@ -287,8 +281,7 @@
 //! ```
 //! Or, should we create a new span for each iteration of the loop, as in:
 //! ```rust
-//! # #[macro_use] extern crate tracing;
-//! # use tracing::Level;
+//! # use tracing::{Level, span};
 //! # let n = 1u64;
 //! for i in 0..n {
 //!     let span = span!(Level::TRACE, "my_loop", iteration = i);
@@ -722,8 +715,7 @@ impl Span {
     /// # Examples
     ///
     /// ```
-    /// #[macro_use] extern crate tracing;
-    /// # use tracing::Level;
+    /// # use tracing::{span, Level};
     /// let span = span!(Level::INFO, "my_span");
     /// let guard = span.enter();
     ///
@@ -738,7 +730,7 @@ impl Span {
     /// Guards need not be explicitly dropped:
     ///
     /// ```
-    /// #[macro_use] extern crate tracing;
+    /// # use tracing::trace_span;
     /// fn my_function() -> String {
     ///     // enter a span for the duration of this function.
     ///     let span = trace_span!("my_function");
@@ -760,7 +752,7 @@ impl Span {
     /// entered:
     ///
     /// ```
-    /// #[macro_use] extern crate tracing;
+    /// # use tracing::{info, info_span};
     /// let span = info_span!("my_great_span");
     ///
     /// {
@@ -1070,8 +1062,7 @@ impl Span {
     /// # Examples
     ///
     /// ```
-    /// # #[macro_use] extern crate tracing;
-    /// # use tracing::Level;
+    /// # use tracing::{trace, span, Level};
     /// let my_span = span!(Level::TRACE, "my_span");
     ///
     /// my_span.in_scope(|| {