From cd7526873c9fbc224bed593dab6665ce92d0ec9d Mon Sep 17 00:00:00 2001
From: Alice Ryhl <alice@ryhl.io>
Date: Thu, 28 Jan 2021 14:09:14 +0100
Subject: [PATCH] net: improve discoverability of TcpSocket (#3471)

---
 tokio/src/net/addr.rs         |  2 --
 tokio/src/net/tcp/listener.rs |  7 ++++---
 tokio/src/net/tcp/stream.rs   | 19 +++++++++++--------
 3 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/tokio/src/net/addr.rs b/tokio/src/net/addr.rs
index 7cbe531b14f..ec4fa198ec1 100644
--- a/tokio/src/net/addr.rs
+++ b/tokio/src/net/addr.rs
@@ -8,8 +8,6 @@ use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV
 /// # DNS
 ///
 /// Implementations of `ToSocketAddrs` for string types require a DNS lookup.
-/// These implementations are only provided when Tokio is used with the
-/// **`net`** feature flag.
 ///
 /// # Calling
 ///
diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs
index a13f1d34258..1ff094964b9 100644
--- a/tokio/src/net/tcp/listener.rs
+++ b/tokio/src/net/tcp/listener.rs
@@ -64,9 +64,6 @@ impl TcpListener {
     /// method.
     ///
     /// The address type can be any implementor of the [`ToSocketAddrs`] trait.
-    /// Note that strings only implement this trait when the **`net`** feature
-    /// is enabled, as strings may contain domain names that need to be resolved.
-    ///
     /// If `addr` yields multiple addresses, bind will be attempted with each of
     /// the addresses until one succeeds and returns the listener. If none of
     /// the addresses succeed in creating a listener, the error returned from
@@ -74,7 +71,11 @@ impl TcpListener {
     ///
     /// This function sets the `SO_REUSEADDR` option on the socket.
     ///
+    /// To configure the socket before binding, you can use the [`TcpSocket`]
+    /// type.
+    ///
     /// [`ToSocketAddrs`]: trait@crate::net::ToSocketAddrs
+    /// [`TcpSocket`]: struct@crate::net::TcpSocket
     ///
     /// # Examples
     ///
diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs
index 11b706b625a..91e357f4445 100644
--- a/tokio/src/net/tcp/stream.rs
+++ b/tokio/src/net/tcp/stream.rs
@@ -25,7 +25,8 @@ cfg_net! {
     /// 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`] method, or by [accepting] a connection from a [listener]. A
+    /// TCP stream can also be created via the [`TcpSocket`] type.
     ///
     /// Reading and writing to a `TcpStream` is usually done using the
     /// convenience methods found on the [`AsyncReadExt`] and [`AsyncWriteExt`]
@@ -34,6 +35,7 @@ cfg_net! {
     /// [`connect`]: method@TcpStream::connect
     /// [accepting]: method@crate::net::TcpListener::accept
     /// [listener]: struct@crate::net::TcpListener
+    /// [`TcpSocket`]: struct@crate::net::TcpSocket
     /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
     /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
     ///
@@ -76,16 +78,17 @@ impl TcpStream {
     /// Opens a TCP connection to a remote host.
     ///
     /// `addr` is an address of the remote host. Anything which implements the
-    /// [`ToSocketAddrs`] trait can be supplied as the address. Note that
-    /// strings only implement this trait when the **`net`** feature is enabled,
-    /// as strings may contain domain names that need to be resolved.
+    /// [`ToSocketAddrs`] trait can be supplied as the address.  If `addr`
+    /// yields multiple addresses, connect will be attempted with each of the
+    /// addresses until a connection is successful. If none of the addresses
+    /// result in a successful connection, the error returned from the last
+    /// connection attempt (the last address) is returned.
     ///
-    /// If `addr` yields multiple addresses, connect will be attempted with each
-    /// of the addresses until a connection is successful. If none of the
-    /// addresses result in a successful connection, the error returned from the
-    /// last connection attempt (the last address) is returned.
+    /// To configure the socket before connecting, you can use the [`TcpSocket`]
+    /// type.
     ///
     /// [`ToSocketAddrs`]: trait@crate::net::ToSocketAddrs
+    /// [`TcpSocket`]: struct@crate::net::TcpSocket
     ///
     /// # Examples
     ///