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.

16 files changed, 162 insertions, 126 deletions

diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index cd7a62ea..967d82a6 100644
--- a/tokio/src/lib.rs
+++ b/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
diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs
index 1e660d8f..959eed22 100644
--- a/tokio/src/macros/cfg.rs
+++ b/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
+        )*
     }
 }
diff --git a/tokio/src/net/addr.rs b/tokio/src/net/addr.rs
index aa66c5fa..8e3bf434 100644
--- a/tokio/src/net/addr.rs
+++ b/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.
 ///
diff --git a/tokio/src/net/mod.rs b/tokio/src/net/mod.rs
index ac913b21..a7b98cdb 100644
--- a/tokio/src/net/mod.rs
+++ b/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;
 }
diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs
index 5db5ee80..59762b13 100644
--- a/tokio/src/net/tcp/listener.rs
+++ b/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 {
diff --git a/tokio/src/net/tcp/mod.rs b/tokio/src/net/tcp/mod.rs
index 929a1e00..d5354b38 100644
--- a/tokio/src/net/tcp/mod.rs
+++ b/tokio/src/net/tcp/mod.rs
@@ -1,22 +1,7 @@
-//! 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;
@@ -24,5 +9,5 @@ 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;
diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs
index 34d3a493..b961e363 100644
--- a/tokio/src/net/tcp/stream.rs
+++ b/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 {
diff --git a/tokio/src/net/udp/mod.rs b/tokio/src/net/udp/mod.rs
index b4d3ea46..a616f4d5 100644
--- a/tokio/src/net/udp/mod.rs
+++ b/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};
diff --git a/tokio/src/net/udp/socket.rs b/tokio/src/net/udp/socket.rs
index 30cc104e..c22ebd92 100644
--- a/tokio/src/net/udp/socket.rs
+++ b/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 {
diff --git a/tokio/src/net/unix/datagram.rs b/tokio/src/net/unix/datagram.rs
index eb8bfe4c..ae1372f6 100644
--- a/tokio/src/net/unix/datagram.rs
+++ b/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 {
diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs
index 7791b05f..5f4787ec 100644
--- a/tokio/src/net/unix/listener.rs
+++ b/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 {
diff --git a/tokio/src/net/unix/mod.rs b/tokio/src/net/unix/mod.rs
index 1ec6fa8e..ddba60d1 100644
--- a/tokio/src/net/unix/mod.rs
+++ b/tokio/src/net/unix/mod.rs
@@ -1,21 +1,18 @@
-//! Unix Domain Sockets for Tokio.
-//!
-//! This crate provides APIs for using Unix Domain Sockets with Tokio.
+//! Unix domain socket utility types
 
-mod datagram;
-pub use datagram::UnixDatagram;
+pub(crate) mod datagram;
 
 mod incoming;
 pub use incoming::Incoming;
 
-mod listener;
-pub use listener::UnixListener;
+pub(crate) mod listener;
+pub(crate) use listener::UnixListener;
 
 mod split;
 pub use split::{ReadHalf, WriteHalf};
 
-mod stream;
-pub use stream::UnixStream;
+pub(crate) mod stream;
+pub(crate) use stream::UnixStream;
 
 mod ucred;
 pub use ucred::UCred;
diff --git a/tokio/src/net/unix/stream.rs b/tokio/src/net/unix/stream.rs
index a430fa17..5151b08a 100644
--- a/tokio/src/net/unix/stream.rs
+++ b/tokio/src/net/unix/stream.rs
@@ -14,13 +14,15 @@ use std::path::Path;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-/// A structure representing a connected Unix socket.
-///
-/// This socket can be connected directly with `UnixStream::connect` or accepted
-/// from a listener with `UnixListener::incoming`. Additionally, a pair of
-/// anonymous Unix sockets can be created with `UnixStream::pair`.
-pub struct UnixStream {
-    io: PollEvented<mio_uds::UnixStream>,
+cfg_uds! {
+    /// A structure representing a connected Unix socket.
+    ///
+    /// This socket can be connected directly with `UnixStream::connect` or accepted
+    /// from a listener with `UnixListener::incoming`. Additionally, a pair of
+    /// anonymous Unix sockets can be created with `UnixStream::pair`.
+    pub struct UnixStream {
+        io: PollEvented<mio_uds::UnixStream>,
+    }
 }
 
 impl UnixStream {
diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs
index 36bab7bc..124027f9 100644
--- a/tokio/src/sync/watch.rs
+++ b/tokio/src/sync/watch.rs
@@ -45,10 +45,11 @@
 //! threads and can be used in a concurrent environment. Clones of [`Receiver`]
 //! handles may be moved to separate threads and also used concurrently.
 //!
-//! [`Sender`]: struct.Sender.html
-//! [`Receiver`]: struct.Receiver.html
-//! [`channel`]: fn.channel.html
-//! [`Sender::closed`]: struct.Sender.html#method.closed
+//! [`Sender`]: crate::sync::watch::Sender
+//! [`Receiver`]: crate::sync::watch::Receiver
+//! [`Receiver::recv`]: crate::sync::watch::Receiver::recv
+//! [`channel`]: crate::sync::watch::channel
+//! [`Sender::closed`]: crate::sync::watch::Sender::closed
 
 use crate::future::poll_fn;
 use crate::sync::task::AtomicWaker;
diff --git a/tokio/tests/uds_datagram.rs b/tokio/tests/uds_datagram.rs
index 504ede52..dd995237 100644
--- a/tokio/tests/uds_datagram.rs
+++ b/tokio/tests/uds_datagram.rs
@@ -2,7 +2,7 @@
 #![cfg(feature = "full")]
 #![cfg(unix)]
 
-use tokio::net::unix::*;
+use tokio::net::UnixDatagram;
 
 use std::io;
 
diff --git a/tokio/tests/uds_stream.rs b/tokio/tests/uds_stream.rs
index 33279590..15760e22 100644
--- a/tokio/tests/uds_stream.rs
+++ b/tokio/tests/uds_stream.rs
@@ -3,7 +3,7 @@
 #![cfg(unix)]
 
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
-use tokio::net::unix::*;
+use tokio::net::{UnixListener, UnixStream};
 
 use futures::future::try_join;