"use of undeclared crate or module mio" when building docs of dependent on nightly with --cfg docsrs

[jwodder]

Version
tokio v1.34.0
tokio-macros v2.2.0
tokio-stream v0.1.14

Platform
Darwin Johns-Laptop-4.local 23.1.0 Darwin Kernel Version 23.1.0: Mon Oct 9 21:27:27 PDT 2023; root:xnu-10002.41.9~6/RELEASE_X86_64 x86_64

Description

I have a library that has an optional dependency on tokio, and it uses docs.rs' support for marking feature-gated items. When I attempt to generate the documentation with the feature-gate annotations locally by running RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features, I get the following errors:

A lot of "use of undeclared crate or module `mio`"

 Documenting tokio v1.34.0
error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:23:6
   |
23 | impl mio::event::Source for NotDefinedHere {
   |      ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
23 | impl io::event::Source for NotDefinedHere {
   |      ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:26:20
   |
26 |         registry: &mio::Registry,
   |                    ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
26 |         registry: &io::Registry,
   |                    ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:27:16
   |
27 |         token: mio::Token,
   |                ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
27 |         token: io::Token,
   |                ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:28:20
   |
28 |         interests: mio::Interest,
   |                    ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
28 |         interests: io::Interest,
   |                    ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:34:20
   |
34 |         registry: &mio::Registry,
   |                    ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
34 |         registry: &io::Registry,
   |                    ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:35:16
   |
35 |         token: mio::Token,
   |                ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
35 |         token: io::Token,
   |                ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:36:20
   |
36 |         interests: mio::Interest,
   |                    ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
36 |         interests: io::Interest,
   |                    ~~

error[E0433]: failed to resolve: use of undeclared crate or module `mio`
  --> /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/doc/mod.rs:40:41
   |
40 |     fn deregister(&mut self, registry: &mio::Registry) -> std::io::Result<()> {
   |                                         ^^^ use of undeclared crate or module `mio`
   |
help: there is a crate or module with a similar name
   |
40 |     fn deregister(&mut self, registry: &io::Registry) -> std::io::Result<()> {
   |                                         ~~

For more information about this error, try `rustc --explain E0433`.
error: could not document `tokio`

Caused by:
  process didn't exit successfully: `/Users/jwodder/.rustup/toolchains/nightly-x86_64-apple-darwin/bin/rustdoc --edition=2021 --crate-type lib --crate-name tokio /Users/jwodder/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.34.0/src/lib.rs --cap-lints allow -o /Users/jwodder/work/rust/crates/serde-jsonlines/target/doc --cfg 'feature="bytes"' --cfg 'feature="default"' --cfg 'feature="io-util"' --cfg 'feature="sync"' --cfg 'feature="time"' --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -C metadata=8354b924c2a8d514 -L dependency=/Users/jwodder/work/rust/crates/serde-jsonlines/target/debug/deps --extern bytes=/Users/jwodder/work/rust/crates/serde-jsonlines/target/debug/deps/libbytes-1397ea7842f2e030.rmeta --extern pin_project_lite=/Users/jwodder/work/rust/crates/serde-jsonlines/target/debug/deps/libpin_project_lite-c25a7c667a708513.rmeta --cfg docsrs --crate-version 1.34.0` (exit status: 1)

The docs build successfully if I omit RUSTDOCFLAGS="--cfg docsrs", --all-features, and/or +nightly. The docs also built fine on docs.rs twelve hours ago.

For the record, the tokio parts of my Cargo.toml are:

[dependencies]
futures = { version = "0.3.25", default-features = false, optional = true }
pin-project-lite = { version = "0.2.9", optional = true }
tokio = { version = "1.21.2", features = ["io-util"], optional = true }
tokio-stream = { version = "0.1.11", optional = true }

[dev-dependencies]
tokio = { version = "1.21.2", features = ["fs", "macros", "rt", "rt-multi-thread"] }

[features]
async = ["dep:futures", "dep:pin-project-lite", "dep:tokio", "dep:tokio-stream"]

[Darksonn]

It sounds like Tokio only compiles under --cfg docsrs when all features are enabled.

That said, you said that you are using RUSTDOCFLAGS only, and not RUSTFLAGS when documenting your own crate? That is very confusing to me, because RUSTDOCFLAGS only applies to the crate being documented, and not to dependencies, so I'm not sure how this affected Tokio. Are you also documenting Tokio itself directly?

[jwodder]

Are you also documenting Tokio itself directly?

Nope, I'm just running RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features on my own project.

[udoprog]

How about renaming the flag used by tokio from docsrs to tokio_docsrs to mitigate future conflicts?