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

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.

Author: hds

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]

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;
 

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

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};

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};

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};

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::{

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)]

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

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;