From 78e0f0b42a4f7a50f3986f576703e5a3cb473b79 Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Tue, 21 Dec 2021 11:11:48 -0800 Subject: [PATCH] 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 | 8 ++++++++ tokio/Cargo.toml | 6 +++++- tokio/src/macros/cfg.rs | 4 ++-- tokio/src/runtime/stats/mod.rs | 6 ++++++ tokio/src/runtime/stats/stats.rs | 12 ++++++++++++ tokio/src/task/builder.rs | 10 ++++++++++ 6 files changed, 43 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66ec614e5..289e069a3 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/tokio/Cargo.toml b/tokio/Cargo.toml index 06ef70740..2a88b766c 100644 --- a/tokio/Cargo.toml +++ b/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"] diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs index 4ab13c2c1..9fa30ca27 100644 --- a/tokio/src/macros/cfg.rs +++ b/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 )* }; diff --git a/tokio/src/runtime/stats/mod.rs b/tokio/src/runtime/stats/mod.rs index 5e08e8ec4..355e40060 100644 --- a/tokio/src/runtime/stats/mod.rs +++ b/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! { diff --git a/tokio/src/runtime/stats/stats.rs b/tokio/src/runtime/stats/stats.rs index b2bcaccaa..375786300 100644 --- a/tokio/src/runtime/stats/stats.rs +++ b/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 { diff --git a/tokio/src/task/builder.rs b/tokio/src/task/builder.rs index dae334928..0a7fe3c37 100644 --- a/tokio/src/task/builder.rs +++ b/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>, }