From 772e0ca8a678138ad4efa4d4b1f0ea544bca9bbe Mon Sep 17 00:00:00 2001
From: Jonas Fassbender <jonas@fc-web.de>
Date: Wed, 13 Nov 2024 17:28:55 +0100
Subject: [PATCH] docs: fix documentation build on Windows (#6945)

---
 .github/workflows/ci.yml            | 22 +++++++++++++++-------
 tokio/src/io/mod.rs                 |  3 +++
 tokio/src/lib.rs                    |  7 ++++---
 tokio/src/net/tcp/socket.rs         |  3 +++
 tokio/src/net/windows/named_pipe.rs |  4 ++--
 tokio/src/signal/windows.rs         |  8 +++++---
 6 files changed, 32 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e5b025ce0..e2a5aef9f 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
@@ -1106,11 +1114,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 99cabde0a..dc2c4309e 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 9bac62c4d..7b84b54b8 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 a9ba3b066..33b714854 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 0b312f896..417e67b31 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 d8af9b4c9..43dab808b 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;