doc: restructure project to enable cross-platform rustdoc

tokio/src/io/async_fd.rs

@@ -3,7 +3,7 @@ use crate::io::driver::{Handle, Interest, ReadyEvent, Registration};
 use mio::unix::SourceFd;
 use std::io;
 use std::os::unix::io::{AsRawFd, RawFd};
-use std::{task::Context, task::Poll};
+use std::task::{Context, Poll};
 
 /// Associates an IO object backed by a Unix file descriptor with the tokio
 /// reactor, allowing for readiness to be polled. The file descriptor must be of

tokio/src/macros/cfg.rs

@@ -1,5 +1,44 @@
 #![allow(unused_macros)]
 
+/// Helper for rustdoc to generate cross platform documentation.
+///
+/// This implements the approach taken by libstd and documented in [advanced
+/// features of
+/// rustdoc](https://doc.rust-lang.org/rustdoc/advanced-features.html).
+///
+/// We leverage that the content of functions are largely ignored by rustdoc,
+/// and provide the ability to mock anything that is required for rustdoc to
+/// compile documentation on other platforms
+///
+/// This does have a few downsides:
+/// * Anything outlined in the `mock` section won't *correctly* link to the
+///   correct upstream crate for types used *unless* it's built for that
+///   platform.
+/// * Trait implementations that mentions types in the `mock` section won't be
+///   visible in generated documentation *unless* it's built for that platform.
+macro_rules! doc_prelude {
+    (
+        $vis:vis mod stub {$($stubs:tt)* }
+        $(#[cfg($($meta:meta)*)] { $($items:tt)* })*
+    ) => {
+        #[cfg(docsrs)]
+        #[doc(hidden)]
+        $vis mod doc {
+            $($stubs)*
+        }
+
+        $(
+            #[cfg(all(not(docsrs), $($meta)*))]
+            #[doc(hidden)]
+            $vis mod doc {
+                $($items)*
+            }
+        )*
+
+        $vis use self::doc::*;
+    }
+}
+
 macro_rules! feature {
     (
         #![$meta:meta]
@@ -177,7 +216,7 @@ macro_rules! cfg_net_unix {
     ($($item:item)*) => {
         $(
             #[cfg(all(unix, feature = "net"))]
-            #[cfg_attr(docsrs, doc(cfg(feature = "net")))]
+            #[cfg_attr(docsrs, doc(cfg(all(unix, feature = "net"))))]
             $item
         )*
     }

tokio/src/net/unix/datagram/socket.rs

@@ -399,11 +399,11 @@ impl UnixDatagram {
     /// [`tokio::net::UnixDatagram`]: UnixDatagram
     /// [`std::os::unix::net::UnixDatagram`]: std::os::unix::net::UnixDatagram
     /// [`set_nonblocking`]: fn@std::os::unix::net::UnixDatagram::set_nonblocking
-    pub fn into_std(self) -> io::Result<std::os::unix::net::UnixDatagram> {
+    pub fn into_std(self) -> io::Result<net::UnixDatagram> {
         self.io
             .into_inner()
             .map(|io| io.into_raw_fd())
-            .map(|raw_fd| unsafe { std::os::unix::net::UnixDatagram::from_raw_fd(raw_fd) })
+            .map(|raw_fd| unsafe { net::UnixDatagram::from_raw_fd(raw_fd) })
     }
 
     fn new(socket: mio::net::UnixDatagram) -> io::Result<UnixDatagram> {
@@ -1249,14 +1249,14 @@ impl UnixDatagram {
     }
 }
 
-impl TryFrom<std::os::unix::net::UnixDatagram> for UnixDatagram {
+impl TryFrom<net::UnixDatagram> for UnixDatagram {
     type Error = io::Error;
 
     /// Consumes stream, returning the Tokio I/O object.
     ///
     /// This is equivalent to
     /// [`UnixDatagram::from_std(stream)`](UnixDatagram::from_std).
-    fn try_from(stream: std::os::unix::net::UnixDatagram) -> Result<Self, Self::Error> {
+    fn try_from(stream: net::UnixDatagram) -> Result<Self, Self::Error> {
         Self::from_std(stream)
     }
 }

tokio/src/net/unix/listener.rs

@@ -110,7 +110,7 @@ impl UnixListener {
     /// [`tokio::net::UnixListener`]: UnixListener
     /// [`std::os::unix::net::UnixListener`]: std::os::unix::net::UnixListener
     /// [`set_nonblocking`]: fn@std::os::unix::net::UnixListener::set_nonblocking
-    pub fn into_std(self) -> io::Result<std::os::unix::net::UnixListener> {
+    pub fn into_std(self) -> io::Result<net::UnixListener> {
         self.io
             .into_inner()
             .map(|io| io.into_raw_fd())
@@ -154,14 +154,14 @@ impl UnixListener {
     }
 }
 
-impl TryFrom<std::os::unix::net::UnixListener> for UnixListener {
+impl TryFrom<net::UnixListener> for UnixListener {
     type Error = io::Error;
 
     /// Consumes stream, returning the tokio I/O object.
     ///
     /// This is equivalent to
     /// [`UnixListener::from_std(stream)`](UnixListener::from_std).
-    fn try_from(stream: std::os::unix::net::UnixListener) -> io::Result<Self> {
+    fn try_from(stream: net::UnixListener) -> io::Result<Self> {
         Self::from_std(stream)
     }
 }

tokio/src/net/unix/stream.rs

@@ -546,11 +546,11 @@ impl UnixStream {
     /// [`tokio::net::UnixStream`]: UnixStream
     /// [`std::os::unix::net::UnixStream`]: std::os::unix::net::UnixStream
     /// [`set_nonblocking`]: fn@std::os::unix::net::UnixStream::set_nonblocking
-    pub fn into_std(self) -> io::Result<std::os::unix::net::UnixStream> {
+    pub fn into_std(self) -> io::Result<net::UnixStream> {
         self.io
             .into_inner()
             .map(|io| io.into_raw_fd())
-            .map(|raw_fd| unsafe { std::os::unix::net::UnixStream::from_raw_fd(raw_fd) })
+            .map(|raw_fd| unsafe { net::UnixStream::from_raw_fd(raw_fd) })
     }
 
     /// Creates an unnamed pair of connected sockets.

tokio/src/signal/unix.rs

@@ -4,12 +4,12 @@
 //! `Signal` type for receiving notifications of signals.
 
 #![cfg(unix)]
+#![cfg_attr(docsrs, doc(cfg(all(unix, feature = "signal"))))]
 
 use crate::signal::registry::{globals, EventId, EventInfo, Globals, Init, Storage};
 use crate::signal::RxFuture;
 use crate::sync::watch;
 
-use mio::net::UnixStream;
 use std::io::{self, Error, ErrorKind, Write};
 use std::pin::Pin;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -46,13 +46,13 @@ impl Storage for OsStorage {
 
 #[derive(Debug)]
 pub(crate) struct OsExtraData {
-    sender: UnixStream,
-    receiver: UnixStream,
+    sender: mio::net::UnixStream,
+    receiver: mio::net::UnixStream,
 }
 
 impl Init for OsExtraData {
     fn init() -> Self {
-        let (receiver, sender) = UnixStream::pair().expect("failed to create UnixStream");
+        let (receiver, sender) = mio::net::UnixStream::pair().expect("failed to create UnixStream");
 
         Self { sender, receiver }
     }

tokio/src/signal/unix/driver.rs

@@ -9,6 +9,8 @@ use crate::signal::registry::globals;
 
 use mio::net::UnixStream;
 use std::io::{self, Read};
+use std::os::unix::io::{AsRawFd, FromRawFd};
+use std::os::unix::net;
 use std::ptr;
 use std::sync::{Arc, Weak};
 use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
@@ -45,7 +47,6 @@ impl Driver {
     /// Creates a new signal `Driver` instance that delegates wakeups to `park`.
     pub(crate) fn new(park: IoDriver) -> io::Result<Self> {
         use std::mem::ManuallyDrop;
-        use std::os::unix::io::{AsRawFd, FromRawFd};
 
         // NB: We give each driver a "fresh" reciever file descriptor to avoid
         // the issues described in alexcrichton/tokio-process#42.
@@ -71,8 +72,7 @@ impl Driver {
         let receiver_fd = globals().receiver.as_raw_fd();
 
         // safety: there is nothing unsafe about this, but the `from_raw_fd` fn is marked as unsafe.
-        let original =
-            ManuallyDrop::new(unsafe { std::os::unix::net::UnixStream::from_raw_fd(receiver_fd) });
+        let original = ManuallyDrop::new(unsafe { net::UnixStream::from_raw_fd(receiver_fd) });
         let receiver = UnixStream::from_std(original.try_clone()?);
         let receiver = PollEvented::new_with_interest_and_handle(
             receiver,

tokio/src/signal/windows.rs

@@ -5,7 +5,8 @@
 //! `SetConsoleCtrlHandler` function which receives events of the type
 //! `CTRL_C_EVENT` and `CTRL_BREAK_EVENT`.
 
-#![cfg(windows)]
+#![cfg(any(docsrs, windows))]
+#![cfg_attr(docsrs, doc(cfg(all(windows, feature = "signal"))))]
 
 use crate::signal::registry::{globals, EventId, EventInfo, Init, Storage};
 use crate::signal::RxFuture;
@@ -14,9 +15,20 @@ use std::convert::TryFrom;
 use std::io;
 use std::sync::Once;
 use std::task::{Context, Poll};
-use winapi::shared::minwindef::{BOOL, DWORD, FALSE, TRUE};
-use winapi::um::consoleapi::SetConsoleCtrlHandler;
-use winapi::um::wincon::{CTRL_BREAK_EVENT, CTRL_C_EVENT};
+
+// helps rustdoc on non-unix platforms.
+doc_prelude! {
+    mod stub {
+        pub(super) struct DWORD(());
+        pub(super) struct BOOL(());
+    }
+
+    #[cfg(windows)] {
+        pub(super) use winapi::shared::minwindef::{BOOL, DWORD, FALSE, TRUE};
+        pub(super) use winapi::um::consoleapi::SetConsoleCtrlHandler;
+        pub(super) use winapi::um::wincon::{CTRL_BREAK_EVENT, CTRL_C_EVENT};
+    }
+}
 
 #[derive(Debug)]
 pub(crate) struct OsStorage {