doc: add more doc_cfg annotations (#1821)

Also makes the `tokio::net::{tcp, udp, unix}` modules only for "utility"
types. The primary types are in `tokio::net` directly.

tokio/src/lib.rs

@@ -72,8 +72,8 @@
 //! * Functions for [running blocking operations][blocking] in an asynchronous
 //!   task context.
 //!
-//! The `tokio::task` module is present only when the "rt-core" feature flag is
-//! enabled.
+//! The [`tokio::task`] module is present only when the "rt-core" feature flag
+//! is enabled.
 //!
 //! [tasks]: task/index.html#what-are-tasks
 //! [`tokio::task`]: crate::task

tokio/src/macros/cfg.rs

@@ -161,6 +161,7 @@ macro_rules! cfg_signal {
     ($($item:item)*) => {
         $(
             #[cfg(feature = "signal")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "signal")))]
             #[cfg(not(loom))]
             $item
         )*
@@ -169,13 +170,21 @@ macro_rules! cfg_signal {
 
 macro_rules! cfg_stream {
     ($($item:item)*) => {
-        $( #[cfg(feature = "stream")] $item )*
+        $(
+            #[cfg(feature = "stream")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "stream")))]
+            $item
+        )*
     }
 }
 
 macro_rules! cfg_sync {
     ($($item:item)*) => {
-        $( #[cfg(feature = "sync")] $item )*
+        $(
+            #[cfg(feature = "sync")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
+            $item
+        )*
     }
 }
 
@@ -187,7 +196,11 @@ macro_rules! cfg_not_sync {
 
 macro_rules! cfg_rt_core {
     ($($item:item)*) => {
-        $( #[cfg(feature = "rt-core")] $item )*
+        $(
+            #[cfg(feature = "rt-core")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "rt-core")))]
+            $item
+        )*
     }
 }
 
@@ -199,7 +212,11 @@ macro_rules! cfg_not_rt_core {
 
 macro_rules! cfg_rt_threaded {
     ($($item:item)*) => {
-        $( #[cfg(feature = "rt-threaded")] $item )*
+        $(
+            #[cfg(feature = "rt-threaded")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "rt-threaded")))]
+            $item
+        )*
     }
 }
 
@@ -211,13 +228,21 @@ macro_rules! cfg_not_rt_threaded {
 
 macro_rules! cfg_tcp {
     ($($item:item)*) => {
-        $( #[cfg(feature = "tcp")] $item )*
+        $(
+            #[cfg(feature = "tcp")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "tcp")))]
+            $item
+        )*
     }
 }
 
 macro_rules! cfg_test_util {
     ($($item:item)*) => {
-        $( #[cfg(feature = "test-util")] $item )*
+        $(
+            #[cfg(feature = "test-util")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "test-util")))]
+            $item
+        )*
     }
 }
 
@@ -229,7 +254,11 @@ macro_rules! cfg_not_test_util {
 
 macro_rules! cfg_time {
     ($($item:item)*) => {
-        $( #[cfg(feature = "time")] $item )*
+        $(
+            #[cfg(feature = "time")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
+            $item
+        )*
     }
 }
 
@@ -241,12 +270,20 @@ macro_rules! cfg_not_time {
 
 macro_rules! cfg_udp {
     ($($item:item)*) => {
-        $( #[cfg(feature = "udp")] $item )*
+        $(
+            #[cfg(feature = "udp")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "udp")))]
+            $item
+        )*
     }
 }
 
 macro_rules! cfg_uds {
     ($($item:item)*) => {
-        $( #[cfg(all(unix, feature = "uds"))] $item )*
+        $(
+            #[cfg(all(unix, feature = "uds"))]
+            #[cfg_attr(docsrs, doc(cfg(feature = "uds")))]
+            $item
+        )*
     }
 }

tokio/src/net/addr.rs

@@ -5,6 +5,14 @@ use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV
 
 /// Convert or resolve without blocking to one or more `SocketAddr` values.
 ///
+/// # DNS
+///
+/// Implementations of `ToSocketAddrs` for string types require a DNS lookup.
+/// These implementations are only provided when Tokio is used with the
+/// **`dns`** feature flag.
+///
+/// # Calling
+///
 /// Currently, this trait is only used as an argument to Tokio functions that
 /// need to reference a target socket address.
 ///

tokio/src/net/mod.rs

@@ -28,15 +28,18 @@ pub use addr::ToSocketAddrs;
 
 cfg_tcp! {
     pub mod tcp;
-    pub use tcp::{TcpListener, TcpStream};
+    pub use tcp::listener::TcpListener;
+    pub use tcp::stream::TcpStream;
 }
 
 cfg_udp! {
     pub mod udp;
-    pub use udp::UdpSocket;
+    pub use udp::socket::UdpSocket;
 }
 
 cfg_uds! {
     pub mod unix;
-    pub use unix::{UnixDatagram, UnixListener, UnixStream};
+    pub use unix::datagram::UnixDatagram;
+    pub use unix::listener::UnixListener;
+    pub use unix::stream::UnixStream;
 }

tokio/src/net/tcp/listener.rs

@@ -9,28 +9,30 @@ use std::io;
 use std::net::{self, SocketAddr};
 use std::task::{Context, Poll};
 
-/// An I/O object representing a TCP socket listening for incoming connections.
-///
-/// # Examples
-///
-/// ```no_run
-/// use tokio::net::TcpListener;
-///
-/// use std::io;
-/// # async fn process_socket<T>(_socket: T) {}
-///
-/// #[tokio::main]
-/// async fn main() -> io::Result<()> {
-///     let mut listener = TcpListener::bind("127.0.0.1:8080").await?;
-///
-///     loop {
-///         let (socket, _) = listener.accept().await?;
-///         process_socket(socket).await;
-///     }
-/// }
-/// ```
-pub struct TcpListener {
-    io: PollEvented<mio::net::TcpListener>,
+cfg_tcp! {
+    /// A TCP socket server, listening for connections.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::net::TcpListener;
+    ///
+    /// use std::io;
+    /// # async fn process_socket<T>(_socket: T) {}
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let mut listener = TcpListener::bind("127.0.0.1:8080").await?;
+    ///
+    ///     loop {
+    ///         let (socket, _) = listener.accept().await?;
+    ///         process_socket(socket).await;
+    ///     }
+    /// }
+    /// ```
+    pub struct TcpListener {
+        io: PollEvented<mio::net::TcpListener>,
+    }
 }
 
 impl TcpListener {

tokio/src/net/tcp/mod.rs

@@ -1,28 +1,13 @@
-//! TCP bindings for `tokio`.
-//!
-//! This module contains the TCP networking types, similar to the standard
-//! library, which can be used to implement networking protocols.
-//!
-//! Connecting to an address, via TCP, can be done using [`TcpStream`]'s
-//! [`connect`] method, which returns a future which returns a `TcpStream`.
-//!
-//! To listen on an address [`TcpListener`] can be used. `TcpListener`'s
-//! [`incoming`][TcpListener::incoming] method can be used to accept new connections.
-//! It return the [`Incoming`] struct, which implements a stream which returns
-//! `TcpStream`s.
-//!
-//! [`TcpStream`]: struct.TcpStream.html
-//! [`connect`]: struct.TcpStream.html#method.connect
-//! [`TcpListener`]: struct.TcpListener.html
+//! TCP utility types
 
-mod listener;
-pub use listener::TcpListener;
+pub(crate) mod listener;
+pub(crate) use listener::TcpListener;
 
 mod incoming;
 pub use incoming::Incoming;
 
 mod split;
 pub use split::{ReadHalf, WriteHalf};
 
-mod stream;
-pub use stream::TcpStream;
+pub(crate) mod stream;
+pub(crate) use stream::TcpStream;

tokio/src/net/tcp/stream.rs

@@ -12,35 +12,37 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 use std::time::Duration;
 
-/// An I/O object representing a TCP stream connected to a remote endpoint.
-///
-/// A TCP stream can either be created by connecting to an endpoint, via the
-/// [`connect`] method, or by [accepting] a connection from a [listener].
-///
-/// [`connect`]: struct.TcpStream.html#method.connect
-/// [accepting]: struct.TcpListener.html#method.accept
-/// [listener]: struct.TcpListener.html
-///
-/// # Examples
-///
-/// ```no_run
-/// use tokio::net::TcpStream;
-/// use tokio::prelude::*;
-/// use std::error::Error;
-///
-/// #[tokio::main]
-/// async fn main() -> Result<(), Box<dyn Error>> {
-///     // Connect to a peer
-///     let mut stream = TcpStream::connect("127.0.0.1:8080").await?;
-///
-///     // Write some data.
-///     stream.write_all(b"hello world!").await?;
-///
-///     Ok(())
-/// }
-/// ```
-pub struct TcpStream {
-    io: PollEvented<mio::net::TcpStream>,
+cfg_tcp! {
+    /// A TCP stream between a local and a remote socket.
+    ///
+    /// A TCP stream can either be created by connecting to an endpoint, via the
+    /// [`connect`] method, or by [accepting] a connection from a [listener].
+    ///
+    /// [`connect`]: struct.TcpStream.html#method.connect
+    /// [accepting]: struct.TcpListener.html#method.accept
+    /// [listener]: struct.TcpListener.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::net::TcpStream;
+    /// use tokio::prelude::*;
+    /// use std::error::Error;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> Result<(), Box<dyn Error>> {
+    ///     // Connect to a peer
+    ///     let mut stream = TcpStream::connect("127.0.0.1:8080").await?;
+    ///
+    ///     // Write some data.
+    ///     stream.write_all(b"hello world!").await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    pub struct TcpStream {
+        io: PollEvented<mio::net::TcpStream>,
+    }
 }
 
 impl TcpStream {

tokio/src/net/udp/mod.rs

@@ -1,14 +1,7 @@
-//! UDP bindings for `tokio`.
-//!
-//! This module contains the UDP networking types, similar to the standard
-//! library, which can be used to implement networking protocols.
-//!
-//! The main struct for UDP is the [`UdpSocket`], which represents a UDP socket.
-//!
-//! [`UdpSocket`]: struct.UdpSocket
+//! UDP utility types.
 
-mod socket;
-pub use socket::UdpSocket;
+pub(crate) mod socket;
+pub(crate) use socket::UdpSocket;
 
 mod split;
 pub use split::{RecvHalf, SendHalf, ReuniteError};

tokio/src/net/udp/socket.rs

@@ -9,9 +9,11 @@ use std::io;
 use std::net::{self, Ipv4Addr, Ipv6Addr, SocketAddr};
 use std::task::{Context, Poll};
 
-/// An I/O object representing a UDP socket.
-pub struct UdpSocket {
-    io: PollEvented<mio::net::UdpSocket>,
+cfg_udp! {
+    /// A UDP socket
+    pub struct UdpSocket {
+        io: PollEvented<mio::net::UdpSocket>,
+    }
 }
 
 impl UdpSocket {

tokio/src/net/unix/datagram.rs

@@ -10,9 +10,11 @@ use std::os::unix::net::{self, SocketAddr};
 use std::path::Path;
 use std::task::{Context, Poll};
 
-/// An I/O object representing a Unix datagram socket.
-pub struct UnixDatagram {
-    io: PollEvented<mio_uds::UnixDatagram>,
+cfg_uds! {
+    /// An I/O object representing a Unix datagram socket.
+    pub struct UnixDatagram {
+        io: PollEvented<mio_uds::UnixDatagram>,
+    }
 }
 
 impl UnixDatagram {

tokio/src/net/unix/listener.rs

@@ -12,9 +12,11 @@ use std::os::unix::net::{self, SocketAddr};
 use std::path::Path;
 use std::task::{Context, Poll};
 
-/// A Unix socket which can accept connections from other Unix sockets.
-pub struct UnixListener {
-    io: PollEvented<mio_uds::UnixListener>,
+cfg_uds! {
+    /// A Unix socket which can accept connections from other Unix sockets.
+    pub struct UnixListener {
+        io: PollEvented<mio_uds::UnixListener>,
+    }
 }
 
 impl UnixListener {