dns: document that strings require the DNS feature (#2663)

2 files changed, 52 insertions, 5 deletions

diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs
index c6d85da2..fd79b259 100644
--- a/tokio/src/net/tcp/listener.rs
+++ b/tokio/src/net/tcp/listener.rs
@@ -72,7 +72,7 @@ cfg_tcp! {
 }
 
 impl TcpListener {
-    /// Creates a new TcpListener which will be bound to the specified address.
+    /// Creates a new TcpListener, which will be bound to the specified address.
     ///
     /// The returned listener is ready for accepting connections.
     ///
@@ -80,7 +80,9 @@ impl TcpListener {
     /// to this listener. The port allocated can be queried via the `local_addr`
     /// method.
     ///
-    /// The address type can be any implementor of `ToSocketAddrs` trait.
+    /// The address type can be any implementor of the [`ToSocketAddrs`] trait.
+    /// Note that strings only implement this trait when the **`dns`** 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
@@ -89,6 +91,8 @@ impl TcpListener {
     ///
     /// This function sets the `SO_REUSEADDR` option on the socket.
     ///
+    /// [`ToSocketAddrs`]: trait@crate::net::ToSocketAddrs
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -98,7 +102,26 @@ impl TcpListener {
     ///
     /// #[tokio::main]
     /// async fn main() -> io::Result<()> {
-    ///     let listener = TcpListener::bind("127.0.0.1:0").await?;
+    ///     let listener = TcpListener::bind("127.0.0.1:2345").await?;
+    ///
+    ///     // use the listener
+    ///
+    ///     # let _ = listener;
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
+    /// Without the `dns` feature:
+    ///
+    /// ```no_run
+    /// use tokio::net::TcpListener;
+    /// use std::net::Ipv4Addr;
+    ///
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let listener = TcpListener::bind((Ipv4Addr::new(127, 0, 0, 1), 2345)).await?;
     ///
     ///     // use the listener
     ///
diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs
index 319ef72e..cc81e116 100644
--- a/tokio/src/net/tcp/stream.rs
+++ b/tokio/src/net/tcp/stream.rs
@@ -63,14 +63,18 @@ cfg_tcp! {
 impl TcpStream {
     /// Opens a TCP connection to a remote host.
     ///
-    /// `addr` is an address of the remote host. Anything which implements
-    /// `ToSocketAddrs` trait can be supplied for the address.
+    /// `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 **`dns`** feature is enabled,
+    /// as strings may contain domain names that need to be resolved.
     ///
     /// 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.
     ///
+    /// [`ToSocketAddrs`]: trait@crate::net::ToSocketAddrs
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -90,6 +94,26 @@ impl TcpStream {
     /// }
     /// ```
     ///
+    /// Without the `dns` feature:
+    ///
+    /// ```no_run
+    /// use tokio::net::TcpStream;
+    /// use tokio::prelude::*;
+    /// use std::error::Error;
+    /// use std::net::Ipv4Addr;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> Result<(), Box<dyn Error>> {
+    ///     // Connect to a peer
+    ///     let mut stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 8080)).await?;
+    ///
+    ///     // Write some data.
+    ///     stream.write_all(b"hello world!").await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
     /// The [`write_all`] method is defined on the [`AsyncWriteExt`] trait.
     ///
     /// [`write_all`]: fn@crate::io::AsyncWriteExt::write_all