From 4485921ba7897f0a0a5e7d6c7602f58e46dba37c Mon Sep 17 00:00:00 2001
From: Cody Casterline <cody.casterline@gmail.com>
Date: Fri, 25 Feb 2022 09:36:37 -0800
Subject: [PATCH] Improve docs for tokio_unstable. (#4524)

---
 .cirrus.yml              |  4 ++--
 .github/workflows/ci.yml |  4 ++--
 tokio/src/lib.rs         | 38 ++++++++++++++++++++++++++++++++++----
 3 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/.cirrus.yml b/.cirrus.yml
index 5916acd96c4..0d58c1e0e8b 100644
--- a/.cirrus.yml
+++ b/.cirrus.yml
@@ -26,8 +26,8 @@ task:
 task:
   name: FreeBSD docs
   env:
-    RUSTFLAGS: --cfg docsrs
-    RUSTDOCFLAGS: --cfg docsrs -Dwarnings
+    RUSTFLAGS: --cfg docsrs --cfg tokio_unstable
+    RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -Dwarnings
   setup_script:
     - pkg install -y bash curl
     - curl https://sh.rustup.rs -sSf --output rustup.sh
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1bb8b52bb1d..e4c7a245244 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -359,8 +359,8 @@ jobs:
       - name: "doc --lib --all-features"
         run: cargo doc --lib --no-deps --all-features --document-private-items
         env:
-          RUSTFLAGS: --cfg docsrs
-          RUSTDOCFLAGS: --cfg docsrs -Dwarnings
+          RUSTFLAGS: --cfg docsrs --cfg tokio_unstable
+          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -Dwarnings
 
   loom-compile:
     name: build loom tests
diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index 2a7887ce584..27d4dc83855 100644
--- a/tokio/src/lib.rs
+++ b/tokio/src/lib.rs
@@ -340,13 +340,43 @@
 //!
 //! ### Unstable features
 //!
-//! These feature flags enable **unstable** features. The public API may break in 1.x
-//! releases. To enable these features, the `--cfg tokio_unstable` must be passed to
-//! `rustc` when compiling. This is easiest done using the `RUSTFLAGS` env variable:
-//! `RUSTFLAGS="--cfg tokio_unstable"`.
+//! Some feature flags are only available when specifying the `tokio_unstable` flag:
 //!
 //! - `tracing`: Enables tracing events.
 //!
+//! Likewise, some parts of the API are only available with the same flag:
+//!
+//! - [`task::JoinSet`]
+//! - [`task::Builder`]
+//!  
+//! This flag enables **unstable** features. The public API of these features
+//! may break in 1.x releases. To enable these features, the `--cfg
+//! tokio_unstable` argument must be passed to `rustc` when compiling. This
+//! serves to explicitly opt-in to features which may break semver conventions,
+//! since Cargo [does not yet directly support such opt-ins][unstable features].
+//!
+//! You can specify it in your project's `.cargo/config.toml` file:
+//!
+//! ```toml
+//! [build]
+//! rustflags = ["--cfg", "tokio_unstable"]
+//! ```
+//!
+//! Alternatively, you can specify it with an environment variable:
+//!
+//! ```sh
+//! ## Many *nix shells:
+//! export RUSTFLAGS="--cfg tokio_unstable"
+//! cargo build
+//! ```
+//!
+//! ```powershell
+//! ## Windows PowerShell:
+//! $Env:RUSTFLAGS="--cfg tokio_unstable"
+//! cargo build
+//! ```
+//!
+//! [unstable features]: https://internals.rust-lang.org/t/feature-request-unstable-opt-in-non-transitive-crate-features/16193#why-not-a-crate-feature-2
 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
 
 // Test that pointer width is compatible. This asserts that e.g. usize is at