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 {