docs: improve RustDoc for unstable features (#4331)

Currently, the docs.rs documentation for tokio is built without
--cfg tokio_unstable set. This means that unstable features are not shown in
the API docs, making them difficutl to discover. Clearly, we do want to
document the existence of unstable APIs, given that there's a section in
the lib.rs documentation listing them, so it would be better if it was
also possible to determine what APIs an unstable feature enables when
reading the RustDoc documentation.

This branch changes the docs.rs metadata to also pass --cfg tokio_unstable
when building the documentation. It turns out that it's
necessary to separately pass the cfg flag to both RustDoc and rustc,
or else the tracing dependency, which is only enabled in
target.cfg(tokio_unstable).dependencies, will be missing and the build
will fail.

In addition, I made some minor improvements to the docs for unstable
features. Some links in the task::Builder docs were broken, and the
required tokio_unstable cfg was missing from the doc(cfg(...))
attributes. Furthermore, I added a note in the top-level docs for
unstable APIs, stating that they are unstable and linking back to the
section in the crate-level docs that explains how to enable unstable
features.

Fixes #4328

CONTRIBUTING.md

@@ -139,6 +139,14 @@ correctly, use this command:
 RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
 ```
 
+To build documentation including Tokio's unstable features, it is necessary to
+pass `--cfg tokio_unstable` to both RustDoc *and* rustc. To build the
+documentation for unstable features, use this command:
+
+```
+RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg tokio_unstable" cargo +nightly doc --all-features
+```
+
 There is currently a [bug in cargo] that means documentation cannot be built
 from the root of the workspace. If you `cd` into the `tokio` subdirectory the
 command shown above will work.

tokio/Cargo.toml

@@ -138,7 +138,11 @@ loom = { version = "0.5", features = ["futures", "checkpoint"] }
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "docsrs"]
+# enable unstable features in the documentation
+rustdoc-args = ["--cfg", "docsrs", "--cfg", "tokio_unstable"]
+# it's necessary to _also_ pass `--cfg tokio_unstable` to rustc, or else
+# dependencies will not be enabled, and the docs build will fail.
+rustc-args = ["--cfg", "tokio_unstable"]
 
 [package.metadata.playground]
 features = ["full", "test-util"]

tokio/src/macros/cfg.rs

@@ -178,7 +178,7 @@ macro_rules! cfg_stats {
     ($($item:item)*) => {
         $(
             #[cfg(all(tokio_unstable, feature = "stats"))]
-            #[cfg_attr(docsrs, doc(cfg(feature = "stats")))]
+            #[cfg_attr(docsrs, doc(cfg(all(tokio_unstable, feature = "stats"))))]
             $item
         )*
     }
@@ -365,7 +365,7 @@ macro_rules! cfg_trace {
     ($($item:item)*) => {
         $(
             #[cfg(all(tokio_unstable, feature = "tracing"))]
-            #[cfg_attr(docsrs, doc(cfg(feature = "tracing")))]
+            #[cfg_attr(docsrs, doc(cfg(all(tokio_unstable, feature = "tracing"))))]
             $item
         )*
     };

tokio/src/runtime/stats/mod.rs

@@ -1,5 +1,11 @@
 //! This module contains information need to view information about how the
 //! runtime is performing.
+//!
+//! **Note**: This is an [unstable API][unstable]. The public API of types in
+//! this module may break in 1.x releases. See [the documentation on unstable
+//! features][unstable] for details.
+//!
+//! [unstable]: crate#unstable-features
 #![allow(clippy::module_inception)]
 
 cfg_stats! {

tokio/src/runtime/stats/stats.rs

@@ -5,12 +5,24 @@ use std::convert::TryFrom;
 use std::time::{Duration, Instant};
 
 /// This type contains methods to retrieve stats from a Tokio runtime.
+///
+/// **Note**: This is an [unstable API][unstable]. The public API of this type
+/// may break in 1.x releases. See [the documentation on unstable
+/// features][unstable] for details.
+///
+/// [unstable]: crate#unstable-features
 #[derive(Debug)]
 pub struct RuntimeStats {
     workers: Box<[WorkerStats]>,
 }
 
 /// This type contains methods to retrieve stats from a worker thread on a Tokio runtime.
+///
+/// **Note**: This is an [unstable API][unstable]. The public API of this type
+/// may break in 1.x releases. See [the documentation on unstable
+/// features][unstable] for details.
+///
+/// [unstable]: crate#unstable-features
 #[derive(Debug)]
 #[repr(align(128))]
 pub struct WorkerStats {

tokio/src/task/builder.rs

@@ -4,6 +4,10 @@ use std::future::Future;
 
 /// Factory which is used to configure the properties of a new task.
 ///
+/// **Note**: This is an [unstable API][unstable]. The public API of this type
+/// may break in 1.x releases. See [the documentation on unstable
+/// features][unstable] for details.
+///
 /// Methods can be chained in order to configure it.
 ///
 /// Currently, there is only one configuration option:
@@ -45,7 +49,13 @@ use std::future::Future;
 ///     }
 /// }
 /// ```
+/// [unstable API]: crate#unstable-features
+/// [`name`]: Builder::name
+/// [`spawn_local`]: Builder::spawn_local
+/// [`spawn`]: Builder::spawn
+/// [`spawn_blocking`]: Builder::spawn_blocking
 #[derive(Default, Debug)]
+#[cfg_attr(docsrs, doc(cfg(all(tokio_unstable, feature = "tracing"))))]
 pub struct Builder<'a> {
     name: Option<&'a str>,
 }