tcp: Update listener docs (#2276)

* Update listener docs
* re-wrap text and add links

tokio/src/net/tcp/listener.rs

@@ -12,10 +12,10 @@ use std::task::{Context, Poll};
 cfg_tcp! {
     /// A TCP socket server, listening for connections.
     ///
-    /// Also implements a stream over the connections being received on this listener.
-    ///
-    /// The stream will never return `None` and will also not yield the peer's
-    /// `SocketAddr` structure. Iterating over it is equivalent to calling accept in a loop.
+    /// You can accept a new connection by using the [`accept`](`TcpListener::accept`) method. Alternatively `TcpListener`
+    /// implements the [`Stream`](`crate::stream::Stream`) trait, which allows you to use the listener in places that want a
+    /// stream. The stream will never return `None` and will also not yield the peer's `SocketAddr` structure.  Iterating over
+    /// it is equivalent to calling accept in a loop.
     ///
     /// # Errors
     ///
@@ -27,7 +27,7 @@ cfg_tcp! {
     ///
     /// # Examples
     ///
-    /// Using [`TcpListener::accept`]:
+    /// Using `accept`:
     /// ```no_run
     /// use tokio::net::TcpListener;
     ///
@@ -278,6 +278,8 @@ impl TcpListener {
 
     /// Returns a stream over the connections being received on this listener.
     ///
+    /// Note that `TcpListener` also directly implements `Stream`.
+    ///
     /// The returned stream will never return `None` and will also not yield the
     /// peer's `SocketAddr` structure. Iterating over it is equivalent to
     /// calling accept in a loop.

tokio/src/net/unix/listener.rs

@@ -15,10 +15,10 @@ use std::task::{Context, Poll};
 cfg_uds! {
     /// A Unix socket which can accept connections from other Unix sockets.
     ///
-    /// Also implements a stream over the connections being received on this listener.
-    ///
-    /// The stream will never return `None` and will also not yield the peer's
-    /// `SocketAddr` structure. Iterating over it is equivalent to calling accept in a loop.
+    /// You can accept a new connection by using the [`accept`](`UnixListener::accept`) method. Alternatively `UnixListener`
+    /// implements the [`Stream`](`crate::stream::Stream`) trait, which allows you to use the listener in places that want a
+    /// stream. The stream will never return `None` and will also not yield the peer's `SocketAddr` structure. Iterating over
+    /// it is equivalent to calling accept in a loop.
     ///
     /// # Errors
     ///
@@ -137,6 +137,8 @@ impl UnixListener {
 
     /// Returns a stream over the connections being received on this listener.
     ///
+    /// Note that `UnixListener` also directly implements `Stream`.
+    ///
     /// The returned stream will never return `None` and will also not yield the
     /// peer's `SocketAddr` structure. Iterating over it is equivalent to
     /// calling accept in a loop.