tokio: make all windows docs visible in unix builds (#5530)

tokio/src/doc/os.rs

@@ -23,6 +23,27 @@ pub mod windows {
             unsafe fn from_raw_handle(handle: RawHandle) -> Self;
         }
 
+        /// See [std::os::windows::io::RawSocket](https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html)
+        pub type RawSocket = crate::doc::NotDefinedHere;
+
+        /// See [std::os::windows::io::AsRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html)
+        pub trait AsRawSocket {
+            /// See [std::os::windows::io::AsRawSocket::as_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html#tymethod.as_raw_socket)
+            fn as_raw_socket(&self) -> RawSocket;
+        }
+
+        /// See [std::os::windows::io::FromRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html)
+        pub trait FromRawSocket {
+            /// See [std::os::windows::io::FromRawSocket::from_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html#tymethod.from_raw_socket)
+            unsafe fn from_raw_socket(sock: RawSocket) -> Self;
+        }
+
+        /// See [std::os::windows::io::IntoRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html)
+        pub trait IntoRawSocket {
+            /// See [std::os::windows::io::IntoRawSocket::into_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html#tymethod.into_raw_socket)
+            fn into_raw_socket(self) -> RawSocket;
+        }
+
         /// See [std::os::windows::io::BorrowedHandle](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedHandle.html)
         pub type BorrowedHandle<'handle> = crate::doc::NotDefinedHere;
 
@@ -31,5 +52,14 @@ pub mod windows {
             /// See [std::os::windows::io::AsHandle::as_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle)
             fn as_handle(&self) -> BorrowedHandle<'_>;
         }
+
+        /// See [std::os::windows::io::BorrowedSocket](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedSocket.html)
+        pub type BorrowedSocket<'socket> = crate::doc::NotDefinedHere;
+
+        /// See [std::os::windows::io::AsSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html)
+        pub trait AsSocket {
+            /// See [std::os::windows::io::AsSocket::as_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket)
+            fn as_socket(&self) -> BorrowedSocket<'_>;
+        }
     }
 }

tokio/src/fs/file.rs

@@ -741,28 +741,32 @@ impl std::os::unix::io::FromRawFd for File {
     }
 }
 
-#[cfg(windows)]
-impl std::os::windows::io::AsRawHandle for File {
-    fn as_raw_handle(&self) -> std::os::windows::io::RawHandle {
-        self.std.as_raw_handle()
-    }
-}
+cfg_windows! {
+    use crate::os::windows::io::{AsRawHandle, FromRawHandle, RawHandle};
+    #[cfg(not(tokio_no_as_fd))]
+    use crate::os::windows::io::{AsHandle, BorrowedHandle};
 
-#[cfg(all(windows, not(tokio_no_as_fd)))]
-impl std::os::windows::io::AsHandle for File {
-    fn as_handle(&self) -> std::os::windows::io::BorrowedHandle<'_> {
-        unsafe {
-            std::os::windows::io::BorrowedHandle::borrow_raw(
-                std::os::windows::io::AsRawHandle::as_raw_handle(self),
-            )
+    impl AsRawHandle for File {
+        fn as_raw_handle(&self) -> RawHandle {
+            self.std.as_raw_handle()
         }
     }
-}
 
-#[cfg(windows)]
-impl std::os::windows::io::FromRawHandle for File {
-    unsafe fn from_raw_handle(handle: std::os::windows::io::RawHandle) -> Self {
-        StdFile::from_raw_handle(handle).into()
+    #[cfg(not(tokio_no_as_fd))]
+    impl AsHandle for File {
+        fn as_handle(&self) -> BorrowedHandle<'_> {
+            unsafe {
+                BorrowedHandle::borrow_raw(
+                    AsRawHandle::as_raw_handle(self),
+                )
+            }
+        }
+    }
+
+    impl FromRawHandle for File {
+        unsafe fn from_raw_handle(handle: RawHandle) -> Self {
+            StdFile::from_raw_handle(handle).into()
+        }
     }
 }
 

tokio/src/fs/mod.rs

@@ -115,9 +115,7 @@ feature! {
     pub use self::symlink::symlink;
 }
 
-feature! {
-    #![windows]
-
+cfg_windows! {
     mod symlink_dir;
     pub use self::symlink_dir::symlink_dir;
 

tokio/src/fs/open_options.rs

@@ -10,6 +10,11 @@ use mock_open_options::MockOpenOptions as StdOpenOptions;
 #[cfg(not(test))]
 use std::fs::OpenOptions as StdOpenOptions;
 
+#[cfg(unix)]
+use std::os::unix::fs::OpenOptionsExt;
+#[cfg(windows)]
+use std::os::windows::fs::OpenOptionsExt;
+
 /// Options and flags which can be used to configure how a file is opened.
 ///
 /// This builder exposes the ability to configure how a [`File`] is opened and
@@ -399,8 +404,6 @@ impl OpenOptions {
 feature! {
     #![unix]
 
-    use std::os::unix::fs::OpenOptionsExt;
-
     impl OpenOptions {
         /// Sets the mode bits that a new file will be created with.
         ///
@@ -464,11 +467,7 @@ feature! {
     }
 }
 
-feature! {
-    #![windows]
-
-    use std::os::windows::fs::OpenOptionsExt;
-
+cfg_windows! {
     impl OpenOptions {
         /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`]
         /// with the specified value.

tokio/src/fs/symlink_dir.rs

@@ -10,7 +10,7 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::os::windows::fs::symlink_dir`][std]
 ///
-/// [std]: std::os::windows::fs::symlink_dir
+/// [std]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_dir.html
 pub async fn symlink_dir(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();

tokio/src/fs/symlink_file.rs

@@ -10,7 +10,7 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::os::windows::fs::symlink_file`][std]
 ///
-/// [std]: std::os::windows::fs::symlink_file
+/// [std]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_file.html
 pub async fn symlink_file(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();

tokio/src/io/stderr.rs

@@ -95,13 +95,10 @@ mod sys {
     }
 }
 
-#[cfg(windows)]
-mod sys {
+cfg_windows! {
     #[cfg(not(tokio_no_as_fd))]
-    use std::os::windows::io::{AsHandle, BorrowedHandle};
-    use std::os::windows::io::{AsRawHandle, RawHandle};
-
-    use super::Stderr;
+    use crate::os::windows::io::{AsHandle, BorrowedHandle};
+    use crate::os::windows::io::{AsRawHandle, RawHandle};
 
     impl AsRawHandle for Stderr {
         fn as_raw_handle(&self) -> RawHandle {

tokio/src/io/stdin.rs

@@ -70,13 +70,10 @@ mod sys {
     }
 }
 
-#[cfg(windows)]
-mod sys {
+cfg_windows! {
     #[cfg(not(tokio_no_as_fd))]
-    use std::os::windows::io::{AsHandle, BorrowedHandle};
-    use std::os::windows::io::{AsRawHandle, RawHandle};
-
-    use super::Stdin;
+    use crate::os::windows::io::{AsHandle, BorrowedHandle};
+    use crate::os::windows::io::{AsRawHandle, RawHandle};
 
     impl AsRawHandle for Stdin {
         fn as_raw_handle(&self) -> RawHandle {

tokio/src/io/stdout.rs

@@ -94,13 +94,10 @@ mod sys {
     }
 }
 
-#[cfg(windows)]
-mod sys {
+cfg_windows! {
     #[cfg(not(tokio_no_as_fd))]
-    use std::os::windows::io::{AsHandle, BorrowedHandle};
-    use std::os::windows::io::{AsRawHandle, RawHandle};
-
-    use super::Stdout;
+    use crate::os::windows::io::{AsHandle, BorrowedHandle};
+    use crate::os::windows::io::{AsRawHandle, RawHandle};
 
     impl AsRawHandle for Stdout {
         fn as_raw_handle(&self) -> RawHandle {

tokio/src/macros/cfg.rs

@@ -13,6 +13,18 @@ macro_rules! feature {
     }
 }
 
+/// Enables Windows-specific code.
+/// Use this macro instead of `cfg(windows)` to generate docs properly.
+macro_rules! cfg_windows {
+    ($($item:item)*) => {
+        $(
+            #[cfg(any(all(doc, docsrs), windows))]
+            #[cfg_attr(docsrs, doc(cfg(windows)))]
+            $item
+        )*
+    }
+}
+
 /// Enables enter::block_on.
 macro_rules! cfg_block_on {
     ($($item:item)*) => {

tokio/src/net/tcp/listener.rs

@@ -437,10 +437,10 @@ cfg_unstable! {
     }
 }
 
-#[cfg(windows)]
-mod sys {
-    use super::TcpListener;
-    use std::os::windows::prelude::*;
+cfg_windows! {
+    use crate::os::windows::io::{AsRawSocket, RawSocket};
+    #[cfg(not(tokio_no_as_fd))]
+    use crate::os::windows::io::{AsSocket, BorrowedSocket};
 
     impl AsRawSocket for TcpListener {
         fn as_raw_socket(&self) -> RawSocket {

tokio/src/net/tcp/socket.rs

@@ -8,12 +8,14 @@ use std::net::SocketAddr;
 use std::os::unix::io::{AsFd, BorrowedFd};
 #[cfg(unix)]
 use std::os::unix::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd};
-#[cfg(windows)]
-use std::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket};
-#[cfg(all(windows, not(tokio_no_as_fd)))]
-use std::os::windows::io::{AsSocket, BorrowedSocket};
 use std::time::Duration;
 
+cfg_windows! {
+    use crate::os::windows::io::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket};
+    #[cfg(not(tokio_no_as_fd))]
+    use crate::os::windows::io::{AsSocket, BorrowedSocket};
+}
+
 cfg_net! {
     /// A TCP socket that has not yet been converted to a `TcpStream` or
     /// `TcpListener`.
@@ -769,37 +771,36 @@ impl IntoRawFd for TcpSocket {
     }
 }
 
-#[cfg(windows)]
-impl IntoRawSocket for TcpSocket {
-    fn into_raw_socket(self) -> RawSocket {
-        self.inner.into_raw_socket()
+cfg_windows! {
+    impl IntoRawSocket for TcpSocket {
+        fn into_raw_socket(self) -> RawSocket {
+            self.inner.into_raw_socket()
+        }
     }
-}
 
-#[cfg(windows)]
-impl AsRawSocket for TcpSocket {
-    fn as_raw_socket(&self) -> RawSocket {
-        self.inner.as_raw_socket()
+    impl AsRawSocket for TcpSocket {
+        fn as_raw_socket(&self) -> RawSocket {
+            self.inner.as_raw_socket()
+        }
     }
-}
 
-#[cfg(all(windows, not(tokio_no_as_fd)))]
-impl AsSocket for TcpSocket {
-    fn as_socket(&self) -> BorrowedSocket<'_> {
-        unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) }
+    #[cfg(not(tokio_no_as_fd))]
+    impl AsSocket for TcpSocket {
+        fn as_socket(&self) -> BorrowedSocket<'_> {
+            unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) }
+        }
     }
-}
 
-#[cfg(windows)]
-impl FromRawSocket for TcpSocket {
-    /// Converts a `RawSocket` to a `TcpStream`.
-    ///
-    /// # Notes
-    ///
-    /// The caller is responsible for ensuring that the socket is in
-    /// non-blocking mode.
-    unsafe fn from_raw_socket(socket: RawSocket) -> TcpSocket {
-        let inner = socket2::Socket::from_raw_socket(socket);
-        TcpSocket { inner }
+    impl FromRawSocket for TcpSocket {
+        /// Converts a `RawSocket` to a `TcpStream`.
+        ///
+        /// # Notes
+        ///
+        /// The caller is responsible for ensuring that the socket is in
+        /// non-blocking mode.
+        unsafe fn from_raw_socket(socket: RawSocket) -> TcpSocket {
+            let inner = socket2::Socket::from_raw_socket(socket);
+            TcpSocket { inner }
+        }
     }
 }

tokio/src/net/tcp/stream.rs

@@ -1387,10 +1387,10 @@ mod sys {
     }
 }
 
-#[cfg(windows)]
-mod sys {
-    use super::TcpStream;
-    use std::os::windows::prelude::*;
+cfg_windows! {
+    use crate::os::windows::io::{AsRawSocket, RawSocket};
+    #[cfg(not(tokio_no_as_fd))]
+    use crate::os::windows::io::{AsSocket, BorrowedSocket};
 
     impl AsRawSocket for TcpStream {
         fn as_raw_socket(&self) -> RawSocket {

tokio/src/net/udp.rs

@@ -1746,10 +1746,10 @@ mod sys {
     }
 }
 
-#[cfg(windows)]
-mod sys {
-    use super::UdpSocket;
-    use std::os::windows::prelude::*;
+cfg_windows! {
+    use crate::os::windows::io::{AsRawSocket, RawSocket};
+    #[cfg(not(tokio_no_as_fd))]
+    use crate::os::windows::io::{AsSocket, BorrowedSocket};
 
     impl AsRawSocket for UdpSocket {
         fn as_raw_socket(&self) -> RawSocket {

tokio/src/process/mod.rs

@@ -249,18 +249,23 @@ use std::convert::TryInto;
 use std::ffi::OsStr;
 use std::future::Future;
 use std::io;
-#[cfg(unix)]
-use std::os::unix::process::CommandExt;
-#[cfg(windows)]
-use std::os::windows::io::{AsRawHandle, RawHandle};
-#[cfg(windows)]
-use std::os::windows::process::CommandExt;
 use std::path::Path;
 use std::pin::Pin;
 use std::process::{Command as StdCommand, ExitStatus, Output, Stdio};
 use std::task::Context;
 use std::task::Poll;
 
+#[cfg(unix)]
+use std::os::unix::process::CommandExt;
+#[cfg(windows)]
+use std::os::windows::process::CommandExt;
+
+cfg_windows! {
+    use crate::os::windows::io::{AsRawHandle, RawHandle};
+    #[cfg(not(tokio_no_as_fd))]
+    use crate::os::windows::io::{AsHandle, BorrowedHandle};
+}
+
 /// This structure mimics the API of [`std::process::Command`] found in the standard library, but
 /// replaces functions that create a process with an asynchronous variant. The main provided
 /// asynchronous functions are [spawn](Command::spawn), [status](Command::status), and
@@ -642,16 +647,16 @@ impl Command {
         self
     }
 
-    /// Sets the [process creation flags][1] to be passed to `CreateProcess`.
-    ///
-    /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`.
-    ///
-    /// [1]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx
-    #[cfg(windows)]
-    #[cfg_attr(docsrs, doc(cfg(windows)))]
-    pub fn creation_flags(&mut self, flags: u32) -> &mut Command {
-        self.std.creation_flags(flags);
-        self
+    cfg_windows! {
+        /// Sets the [process creation flags][1] to be passed to `CreateProcess`.
+        ///
+        /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`.
+        ///
+        /// [1]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx
+        pub fn creation_flags(&mut self, flags: u32) -> &mut Command {
+            self.std.creation_flags(flags);
+            self
+        }
     }
 
     /// Sets the child process's user ID. This translates to a
@@ -1082,13 +1087,14 @@ impl Child {
         }
     }
 
-    /// Extracts the raw handle of the process associated with this child while
-    /// it is still running. Returns `None` if the child has exited.
-    #[cfg(windows)]
-    pub fn raw_handle(&self) -> Option<RawHandle> {
-        match &self.child {
-            FusedChild::Child(c) => Some(c.inner.as_raw_handle()),
-            FusedChild::Done(_) => None,
+    cfg_windows! {
+        /// Extracts the raw handle of the process associated with this child while
+        /// it is still running. Returns `None` if the child has exited.
+        pub fn raw_handle(&self) -> Option<RawHandle> {
+            match &self.child {
+                FusedChild::Child(c) => Some(c.inner.as_raw_handle()),
+                FusedChild::Done(_) => None,
+            }
         }
     }
 
@@ -1323,7 +1329,7 @@ impl ChildStdin {
 }
 
 impl ChildStdout {
-    /// Creates an asynchronous `ChildStderr` from a synchronous one.
+    /// Creates an asynchronous `ChildStdout` from a synchronous one.
     ///
     /// # Errors
     ///
@@ -1474,14 +1480,7 @@ mod sys {
     }
 }
 
-#[cfg(windows)]
-mod sys {
-    #[cfg(not(tokio_no_as_fd))]
-    use std::os::windows::io::{AsHandle, BorrowedHandle};
-    use std::os::windows::io::{AsRawHandle, RawHandle};
-
-    use super::{ChildStderr, ChildStdin, ChildStdout};
-
+cfg_windows! {
     impl AsRawHandle for ChildStdin {
         fn as_raw_handle(&self) -> RawHandle {
             self.inner.as_raw_handle()