Repository: tokio-rs/tokio (language: rust)

Issue:
Unable to use the docsrs configuration under Windows
**Version**
1.38.0

**Platform**
Windows 11 Pro / 64 bit

**Description**
On Windows, the documentation for a project using Tokio cannot be built with `docsrs` enabled.  This makes it difficult-to-impossible to include the automatically generated feature flag details.  More details are available from [this post on the Rust Users forum](https://users.rust-lang.org/t/tokio-rustflags-cfg-docsrs-trouble/112683).

A test project was created with `cargo new tokio-issue-112683`.

Cargo.toml was updated to this...
``` toml
[package]
name = "tokio-issue-112683"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1.38.0", features = ["full"] }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

```

Set the `RUSTFLAGS` environment variable...
`set RUSTFLAGS=--cfg docsrs`

Then try to build the documentation...
`cargo +nightly doc --all-features`

The error list is long...
```
    Checking tokio v1.38.0
error[E0433]: failed to resolve: could not find `unix` in `os`
  --> C:\Users\bcook\.cargo\registry\src\index.crates.io-6f17d22bba15001f\tokio-1.38.0\src\io\bsd\poll_aio.rs:12:14
   |
12 | use std::os::unix::io::AsRawFd;
   |              ^^^^ could not find `unix` in `os`
   |
note: found an item that was configured out
  --> C:\Users\bcook\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\std\src\os\mod.rs:26:9
   |
26 | pub mod unix {}
   |         ^^^^
note: found an item that was configured out
  --> C:\Users\bcook\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\std\src\os\mod.rs:64:9
   |
64 | pub mod unix;
   |         ^^^^

error[E0433]: failed to resolve: could not find `unix` in `os`
  --> C:\Users\bcook\.cargo\registry\src\index.crates.io-6f17d22bba15001f\tokio-1.38.0\src\io\bsd\poll_aio.rs:13:14
   |
13 | use std::os::unix::prelude::RawFd;
   |              ^^^^ could not find `unix` in `os`
   |
note: found an item that was configured out
  --> C:\Users\bcook\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\std\src\os\mod.rs:26:9
   |
26 | pub mod unix {}
   |         ^^^^
note: found an item that was configured out
  --> C:\Users\bcook\.rustup\toolchains\nightly-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\std\src\os\mod.rs:64:9
   |
64 | pub mod unix;
   |         ^^^^

...
```



Discussion / hints:
I think that we should probably only support building docs that include items from all platforms on unix. But trying to build docs on windows should still successfully build docs for the things that are available on windows.
Just ran into this myself on 1.39.2

Fix patch:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 47507d6aaff..2c21a8b49f3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -180,7 +180,7 @@ jobs:
         run: |
           set -euxo pipefail
           RUSTFLAGS="$RUSTFLAGS -C panic=abort -Zpanic-abort-tests" cargo nextest run --workspace --exclude tokio-macros --exclude tests-build --all-features --tests
-  
+
   test-integration-tests-per-feature:
     needs: basics
     name: Run integration tests for each feature
@@ -768,7 +768,15 @@ jobs:
 
   docs:
     name: docs
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.run.os }}
+    strategy:
+      matrix:
+        run:
+          - os: windows-latest
+          - os: ubuntu-latest
+            RUSTFLAGS: --cfg tokio_taskdump
+            RUSTDOCFLAGS: --cfg tokio_taskdump
+
     steps:
       - uses: actions/checkout@v4
       - name: Install Rust ${{ env.rust_nightly }}
@@ -780,8 +788,8 @@ jobs:
         run: |
           cargo doc --lib --no-deps --all-features --document-private-items
         env:
-          RUSTFLAGS: --cfg docsrs --cfg tokio_unstable --cfg tokio_taskdump
-          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable --cfg tokio_taskdump -Dwarnings
+          RUSTFLAGS: --cfg docsrs --cfg tokio_unstable ${{ matrix.run.RUSTFLAGS }}
+          RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -Dwarnings ${{ matrix.run.RUSTDOCFLAGS }}
 
   loom-compile:
     name: build loom tests
@@ -1109,11 +1117,11 @@ jobs:
       - name: Make sure dictionary words are sorted and unique
         run: |
           # `sed` removes the first line (number of words) and
-          # the last line (new line). 
-          # 
+          # the last line (new line).
+          #
           # `sort` makes sure everything in between is sorted
           # and contains no duplicates.
-          # 
+          #
           # Since `sort` is sensitive to locale, we set it
           # using LC_ALL to en_US.UTF8 to be consistent in different
           # environments.
diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs
index 99cabde0ab8..dc2c4309e66 100644
--- a/tokio/src/io/mod.rs
+++ b/tokio/src/io/mod.rs
@@ -231,6 +231,9 @@ cfg_io_driver_impl! {
     pub(crate) use poll_evented::PollEvented;
 }
 
+// The bsd module can't be build on Windows, so we completely ignore it, even
+// when building documentation.
+#[cfg(unix)]
 cfg_aio! {
     /// BSD-specific I/O types.
     pub mod bsd {
diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index 9bac62c4daa..7b84b54b882 100644
--- a/tokio/src/lib.rs
+++ b/tokio/src/lib.rs
@@ -19,6 +19,7 @@
 #![cfg_attr(docsrs, feature(doc_cfg))]
 #![cfg_attr(docsrs, allow(unused_attributes))]
 #![cfg_attr(loom, allow(dead_code, unreachable_pub))]
+#![cfg_attr(windows, allow(rustdoc::broken_intra_doc_links))]
 
 //! A runtime for writing reliable network applications without compromising speed.
 //!
@@ -633,15 +634,15 @@ pub mod stream {}
 // local re-exports of platform specific things, allowing for decent
 // documentation to be shimmed in on docs.rs
 
-#[cfg(docsrs)]
+#[cfg(all(docsrs, unix))]
 pub mod doc;
 
 #[cfg(any(feature = "net", feature = "fs"))]
-#[cfg(docsrs)]
+#[cfg(all(docsrs, unix))]
 #[allow(unused)]
 pub(crate) use self::doc::os;
 
-#[cfg(not(docsrs))]
+#[cfg(not(all(docsrs, unix)))]
 #[allow(unused)]
 pub(crate) use std::os;
 
diff --git a/tokio/src/net/tcp/socket.rs b/tokio/src/net/tcp/socket.rs
index a9ba3b0660d..33b71485473 100644
--- a/tokio/src/net/tcp/socket.rs
+++ b/tokio/src/net/tcp/socket.rs
@@ -787,6 +787,9 @@ impl fmt::Debug for TcpSocket {
     }
 }
 
+// These trait implementations can't be build on Windows, so we completely
+// ignore them, even when building documentation.
+#[cfg(unix)]
 cfg_unix! {
     impl AsRawFd for TcpSocket {
         fn as_raw_fd(&self) -> RawFd {
diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs
index 0b312f896f1..417e67b31dd 100644
--- a/tokio/src/net/windows/named_pipe.rs
+++ b/tokio/src/net/windows/named_pipe.rs
@@ -17,7 +17,7 @@ cfg_io_util! {
 }
 
 // Hide imports which are not used when generating documentation.
-#[cfg(not(docsrs))]
+#[cfg(windows)]
 mod doc {
     pub(super) use crate::os::windows::ffi::OsStrExt;
     pub(super) mod windows_sys {
@@ -30,7 +30,7 @@ mod doc {
 }
 
 // NB: none of these shows up in public API, so don't document them.
-#[cfg(docsrs)]
+#[cfg(not(windows))]
 mod doc {
     pub(super) mod mio_windows {
         pub type NamedPipe = crate::doc::NotDefinedHere;
diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs
index d8af9b4c9d9..43dab808bba 100644
--- a/tokio/src/signal/windows.rs
+++ b/tokio/src/signal/windows.rs
@@ -12,13 +12,15 @@ use crate::signal::RxFuture;
 use std::io;
 use std::task::{Context, Poll};
 
-#[cfg(not(docsrs))]
+#[cfg(windows)]
 #[path = "windows/sys.rs"]
 mod imp;
-#[cfg(not(docsrs))]
+
+#[cfg(windows)]
 pub(crate) use self::imp::{OsExtraData, OsStorage};
 
-#[cfg(docsrs)]
+// For building documentation on Unix machines when the `docsrs` flag is set.
+#[cfg(not(windows))]
 #[path = "windows/stub.rs"]
 mod imp;
 


Test patch: