examples: add note to examples that they are for tracing 0.2.0 (#3099)

hds · web-flow · commit bdbaf8007364 · 2024-10-09T15:31:11.000-04:00
It is not uncommon that users who are new to tracing look at the
examples in the `master` branch of the repository and find that they
don't compile. This is because they are examples which compile with the
code from the master branch, which is for the as yet unreleased tracing
0.2.0 ecosystem.

Users should instead go to the `v0.1.x` branch to find examples
compatible with the crates published on crates.io.

This change adds a doc-comment to the beginning of every example file
informing the user of this fact and suggesting that they check out the
`v0.1.x` branch instead.
diff --git a/examples/examples/all-levels.rs b/examples/examples/all-levels.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 use tracing::Level;
 
 #[no_mangle]
diff --git a/examples/examples/appender-multifile.rs b/examples/examples/appender-multifile.rs
@@ -1,6 +1,8 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! This example demonstrates the use of multiple files with
 //! `tracing-appender`'s `RollingFileAppender`
-//!
 use tracing_appender::rolling;
 use tracing_subscriber::fmt::writer::MakeWriterExt;
 
diff --git a/examples/examples/async-fn.rs b/examples/examples/async-fn.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! Demonstrates using the `trace` attribute macro to instrument `async`
 //! functions.
 //!
diff --git a/examples/examples/attrs-args.rs b/examples/examples/attrs-args.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 
 use tracing::{debug, info};
diff --git a/examples/examples/attrs-basic.rs b/examples/examples/attrs-basic.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 
 use tracing::{debug, info, span, Level};
diff --git a/examples/examples/attrs-literal-field-names.rs b/examples/examples/attrs-literal-field-names.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 
 use tracing::{debug, span, Level};
diff --git a/examples/examples/counters.rs b/examples/examples/counters.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 
 use tracing::{
diff --git a/examples/examples/custom-error.rs b/examples/examples/custom-error.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! This example demonstrates using the `tracing-error` crate's `SpanTrace` type
 //! to attach a trace context to a custom error type.
 #![deny(rust_2018_idioms)]
diff --git a/examples/examples/echo.rs b/examples/examples/echo.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! A "hello world" echo server [from Tokio][echo-example]
 //!
 //! This server will create a TCP listener, accept connections in a loop, and
diff --git a/examples/examples/fmt-compact.rs b/examples/examples/fmt-compact.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 #[path = "fmt/yak_shave.rs"]
 mod yak_shave;
diff --git a/examples/examples/fmt-custom-event.rs b/examples/examples/fmt-custom-event.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 #[path = "fmt/yak_shave.rs"]
 mod yak_shave;
diff --git a/examples/examples/fmt-custom-field.rs b/examples/examples/fmt-custom-field.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! This example demonstrates overriding the way `tracing-subscriber`'s
 //! `FmtSubscriber` formats fields on spans and events, using a closure.
 //!
diff --git a/examples/examples/fmt-json.rs b/examples/examples/fmt-json.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 #[path = "fmt/yak_shave.rs"]
 mod yak_shave;
diff --git a/examples/examples/fmt-multiple-writers.rs b/examples/examples/fmt-multiple-writers.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! An example demonstrating how `fmt::Subcriber` can write to multiple
 //! destinations (in this instance, `stdout` and a file) simultaneously.
 
diff --git a/examples/examples/fmt-pretty.rs b/examples/examples/fmt-pretty.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 #[path = "fmt/yak_shave.rs"]
 mod yak_shave;
diff --git a/examples/examples/fmt-source-locations.rs b/examples/examples/fmt-source-locations.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! Demonstrates displaying events' source code locations with the `fmt`
 //! subscriber.
 #![deny(rust_2018_idioms)]
diff --git a/examples/examples/fmt-stderr.rs b/examples/examples/fmt-stderr.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 use std::io;
 use tracing::error;
diff --git a/examples/examples/fmt.rs b/examples/examples/fmt.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 #[path = "fmt/yak_shave.rs"]
 mod yak_shave;
diff --git a/examples/examples/fmt/yak_shave.rs b/examples/examples/fmt/yak_shave.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 use snafu::{ResultExt, Snafu};
 use std::error::Error;
 use thiserror::Error;
diff --git a/examples/examples/futures-proxy-server.rs b/examples/examples/futures-proxy-server.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! A proxy that forwards data to another server and forwards that server's
 //! responses back to clients.
 //!
diff --git a/examples/examples/hyper-echo.rs b/examples/examples/hyper-echo.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 
 use http::{Method, Request, Response, StatusCode};
diff --git a/examples/examples/inferno-flame.rs b/examples/examples/inferno-flame.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 use std::{
     env,
     fs::File,
diff --git a/examples/examples/instrumented-error.rs b/examples/examples/instrumented-error.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! This example demonstrates using the `tracing-error` crate's `SpanTrace` type
 //! to attach a trace context to a custom error type.
 #![deny(rust_2018_idioms)]
diff --git a/examples/examples/journald.rs b/examples/examples/journald.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 use tracing::{error, info};
 use tracing_subscriber::prelude::*;
diff --git a/examples/examples/log.rs b/examples/examples/log.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 fn main() {
     tracing_subscriber::fmt()
         .with_max_level(tracing::Level::TRACE)
diff --git a/examples/examples/map-traced-error.rs b/examples/examples/map-traced-error.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! An example on composing errors inside of a `TracedError`, such that the
 //! SpanTrace captured is captured when creating the inner error, but still wraps
 //! the outer error.
diff --git a/examples/examples/panic_hook.rs b/examples/examples/panic_hook.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! This example demonstrates how `tracing` events can be recorded from within a
 //! panic hook, capturing the span context in which the program panicked.
 //!
diff --git a/examples/examples/serde-yak-shave.rs b/examples/examples/serde-yak-shave.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 use std::sync::atomic::{AtomicUsize, Ordering};
 
 use tracing::debug;
diff --git a/examples/examples/sloggish/main.rs b/examples/examples/sloggish/main.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! A simple example demonstrating how one might implement a custom
 //! collector.
 //!
diff --git a/examples/examples/sloggish/sloggish_collector.rs b/examples/examples/sloggish/sloggish_collector.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 use nu_ansi_term::{Color, Style};
 use tracing::{
     field::{Field, Visit},
diff --git a/examples/examples/spawny-thing.rs b/examples/examples/spawny-thing.rs
@@ -1,12 +1,14 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//! This is a example showing how information is scoped.
+//!
+//! You can run this example by running the following command in a terminal
+//!
+//! ```
+//! cargo run --example spawny_thing
+//! ```
 #![deny(rust_2018_idioms)]
 
-/// This is a example showing how information is scoped.
-///
-/// You can run this example by running the following command in a terminal
-///
-/// ```
-/// cargo run --example spawny_thing
-/// ```
 use futures::future::join_all;
 use std::error::Error;
 use tracing::{debug, info};
diff --git a/examples/examples/subscriber-filter.rs b/examples/examples/subscriber-filter.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 #![deny(rust_2018_idioms)]
 #[path = "fmt/yak_shave.rs"]
 mod yak_shave;
diff --git a/examples/examples/thread-info.rs b/examples/examples/thread-info.rs
@@ -1,22 +1,25 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
+//! This is a example showing how thread info can be displayed when
+//! formatting events with `tracing_subscriber::fmt`. This is useful
+//! as `tracing` spans can be entered by multiple threads concurrently,
+//! or move across threads freely.
+//!
+//! You can run this example by running the following command in a terminal
+//!
+//! ```
+//! cargo run --example thread-info
+//! ```
+//!
+//! Example output:
+//!
+//! ```not_rust
+//! Jul 17 00:38:07.177  INFO ThreadId(02) thread_info: i=9
+//! Jul 17 00:38:07.177  INFO            thread 1 ThreadId(03) thread_info: i=9
+//! Jul 17 00:38:07.177  INFO large name thread 2 ThreadId(04) thread_info: i=9
+//! ```
 #![deny(rust_2018_idioms)]
-/// This is a example showing how thread info can be displayed when
-/// formatting events with `tracing_subscriber::fmt`. This is useful
-/// as `tracing` spans can be entered by multiple threads concurrently,
-/// or move across threads freely.
-///
-/// You can run this example by running the following command in a terminal
-///
-/// ```
-/// cargo run --example thread-info
-/// ```
-///
-/// Example output:
-///
-/// ```not_rust
-/// Jul 17 00:38:07.177  INFO ThreadId(02) thread_info: i=9
-/// Jul 17 00:38:07.177  INFO            thread 1 ThreadId(03) thread_info: i=9
-/// Jul 17 00:38:07.177  INFO large name thread 2 ThreadId(04) thread_info: i=9
-/// ```
 use std::thread;
 use std::time::Duration;
 use tracing::info;
diff --git a/examples/examples/toggle-subscribers.rs b/examples/examples/toggle-subscribers.rs
@@ -1,14 +1,17 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
+//! This is a example showing how `Subscriber`s can be enabled or disabled by
+//! by wrapping them with an `Option`. This example shows `fmt` and `json`
+//! being toggled based on the `json` command line flag.
+//!
+//! You can run this example by running the following command in a terminal
+//!
+//! ```
+//! cargo run --example toggle-subscribers -- --json
+//! ```
+//!
 #![deny(rust_2018_idioms)]
-/// This is a example showing how `Subscriber`s can be enabled or disabled by
-/// by wrapping them with an `Option`. This example shows `fmt` and `json`
-/// being toggled based on the `json` command line flag.
-///
-/// You can run this example by running the following command in a terminal
-///
-/// ```
-/// cargo run --example toggle-subscribers -- --json
-/// ```
-///
 use argh::FromArgs;
 use tracing::info;
 use tracing_subscriber::{subscribe::CollectExt, util::SubscriberInitExt};
diff --git a/examples/examples/tokio-spawny-thing.rs b/examples/examples/tokio-spawny-thing.rs
@@ -1,12 +1,15 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
+//! This is a example showing how information is scoped with tokio's
+//! `task::spawn`.
+//!
+//! You can run this example by running the following command in a terminal
+//!
+//! ```
+//! cargo run --example tokio-spawny-thing
+//! ```
 #![deny(rust_2018_idioms)]
-/// This is a example showing how information is scoped with tokio's
-/// `task::spawn`.
-///
-/// You can run this example by running the following command in a terminal
-///
-/// ```
-/// cargo run --example tokio-spawny-thing
-/// ```
 use futures::future::try_join_all;
 use tracing::{debug, info, instrument, span, Instrument as _, Level};
 
diff --git a/examples/examples/tokio_panic_hook.rs b/examples/examples/tokio_panic_hook.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! This example demonstrates that a custom panic hook can be used to log panic
 //! messages even when panics are captured (such as when a Tokio task panics).
 //!
diff --git a/examples/examples/tower-client.rs b/examples/examples/tower-client.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 use http::{Method, Request, Uri};
 use hyper::{client::Client, Body};
 use std::time::Duration;
diff --git a/examples/examples/tower-load.rs b/examples/examples/tower-load.rs
@@ -1,3 +1,6 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
+//!
 //! A demo showing how filtering on values and dynamic filter reloading can be
 //! used together to help make sense of complex or noisy traces.
 //!
diff --git a/examples/examples/tower-server.rs b/examples/examples/tower-server.rs
@@ -1,3 +1,5 @@
+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the
+//! release examples, please see the `v0.1.x` branch instead.
 use futures::future;
 use http::{Request, Response};
 use hyper::{Body, Server};

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! NOTE: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem. For the`
	`2`	+//! release examples, please see the `v0.1.x` branch instead.
`1`	`3`	`use tracing::Level;`
`2`	`4`
`3`	`5`	`#[no_mangle]`