docs: make it easier to discover extension traits (#2434)

Refs: #2307

3 files changed, 68 insertions, 6 deletions

diff --git a/tokio/src/net/tcp/split.rs b/tokio/src/net/tcp/split.rs
index 39dca996..469056ac 100644
--- a/tokio/src/net/tcp/split.rs
+++ b/tokio/src/net/tcp/split.rs
@@ -19,14 +19,32 @@ use std::net::Shutdown;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-/// Read half of a `TcpStream`.
+/// Read half of a [`TcpStream`], created by [`split`].
+///
+/// Reading from a `ReadHalf` is usually done using the convenience methods found on the
+/// [`AsyncReadExt`] trait. Examples import this trait through [the prelude].
+///
+/// [`TcpStream`]: TcpStream
+/// [`split`]: TcpStream::split()
+/// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
+/// [the prelude]: crate::prelude
 #[derive(Debug)]
 pub struct ReadHalf<'a>(&'a TcpStream);
 
-/// Write half of a `TcpStream`.
+/// Write half of a [`TcpStream`], created by [`split`].
 ///
-/// Note that in the `AsyncWrite` implemenation of this type, `poll_shutdown` will
+/// Note that in the [`AsyncWrite`] implemenation of this type, [`poll_shutdown`] will
 /// shut down the TCP stream in the write direction.
+///
+/// Writing to an `OwnedWriteHalf` is usually done using the convenience methods found
+/// on the [`AsyncWriteExt`] trait. Examples import this trait through [the prelude].
+///
+/// [`TcpStream`]: TcpStream
+/// [`split`]: TcpStream::split()
+/// [`AsyncWrite`]: trait@crate::io::AsyncWrite
+/// [`poll_shutdown`]: fn@crate::io::AsyncWrite::poll_shutdown
+/// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
+/// [the prelude]: crate::prelude
 #[derive(Debug)]
 pub struct WriteHalf<'a>(&'a TcpStream);
 
@@ -74,6 +92,8 @@ impl ReadHalf<'_> {
     ///
     /// See the [`TcpStream::peek`] level documenation for more details.
     ///
+    /// [`TcpStream::peek`]: TcpStream::peek
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -101,7 +121,10 @@ impl ReadHalf<'_> {
     /// }
     /// ```
     ///
-    /// [`TcpStream::peek`]: TcpStream::peek
+    /// The [`read`] method is defined on the [`AsyncReadExt`] trait.
+    ///
+    /// [`read`]: fn@crate::io::AsyncReadExt::read
+    /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
     pub async fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         poll_fn(|cx| self.poll_peek(cx, buf)).await
     }
diff --git a/tokio/src/net/tcp/split_owned.rs b/tokio/src/net/tcp/split_owned.rs
index 908a39e2..ff82f6ed 100644
--- a/tokio/src/net/tcp/split_owned.rs
+++ b/tokio/src/net/tcp/split_owned.rs
@@ -23,8 +23,13 @@ use std::{fmt, io};
 
 /// Owned read half of a [`TcpStream`], created by [`into_split`].
 ///
+/// Reading from an `OwnedReadHalf` is usually done using the convenience methods found
+/// on the [`AsyncReadExt`] trait. Examples import this trait through [the prelude].
+///
 /// [`TcpStream`]: TcpStream
 /// [`into_split`]: TcpStream::into_split()
+/// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
+/// [the prelude]: crate::prelude
 #[derive(Debug)]
 pub struct OwnedReadHalf {
     inner: Arc<TcpStream>,
@@ -32,13 +37,20 @@ pub struct OwnedReadHalf {
 
 /// Owned write half of a [`TcpStream`], created by [`into_split`].
 ///
-/// Note that in the `AsyncWrite` implemenation of this type, `poll_shutdown` will
+/// Note that in the [`AsyncWrite`] implemenation of this type, [`poll_shutdown`] will
 /// shut down the TCP stream in the write direction.
 ///
 /// Dropping the write half will close the TCP stream in both directions.
 ///
+/// Writing to an `OwnedWriteHalf` is usually done using the convenience methods found
+/// on the [`AsyncWriteExt`] trait. Examples import this trait through [the prelude].
+///
 /// [`TcpStream`]: TcpStream
 /// [`into_split`]: TcpStream::into_split()
+/// [`AsyncWrite`]: trait@crate::io::AsyncWrite
+/// [`poll_shutdown`]: fn@crate::io::AsyncWrite::poll_shutdown
+/// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
+/// [the prelude]: crate::prelude
 #[derive(Debug)]
 pub struct OwnedWriteHalf {
     inner: Arc<TcpStream>,
@@ -136,6 +148,8 @@ impl OwnedReadHalf {
     ///
     /// See the [`TcpStream::peek`] level documenation for more details.
     ///
+    /// [`TcpStream::peek`]: TcpStream::peek
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -163,7 +177,10 @@ impl OwnedReadHalf {
     /// }
     /// ```
     ///
-    /// [`TcpStream::peek`]: TcpStream::peek
+    /// The [`read`] method is defined on the [`AsyncReadExt`] trait.
+    ///
+    /// [`read`]: fn@crate::io::AsyncReadExt::read
+    /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
     pub async fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         poll_fn(|cx| self.poll_peek(cx, buf)).await
     }
diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs
index 03489152..ee44f810 100644
--- a/tokio/src/net/tcp/stream.rs
+++ b/tokio/src/net/tcp/stream.rs
@@ -21,9 +21,16 @@ cfg_tcp! {
     /// A TCP stream can either be created by connecting to an endpoint, via the
     /// [`connect`] method, or by [accepting] a connection from a [listener].
     ///
+    /// Reading and writing to a `TcpStream` is usually done using the
+    /// convenience methods found on the [`AsyncReadExt`] and [`AsyncWriteExt`]
+    /// traits. Examples import these traits through [the prelude].
+    ///
     /// [`connect`]: method@TcpStream::connect
     /// [accepting]: method@super::TcpListener::accept
     /// [listener]: struct@super::TcpListener
+    /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
+    /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
+    /// [the prelude]: crate::prelude
     ///
     /// # Examples
     ///
@@ -43,6 +50,11 @@ cfg_tcp! {
     ///     Ok(())
     /// }
     /// ```
+    ///
+    /// The [`write_all`] method is defined on the [`AsyncWriteExt`] trait.
+    ///
+    /// [`write_all`]: fn@crate::io::AsyncWriteExt::write_all
+    /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
     pub struct TcpStream {
         io: PollEvented<mio::net::TcpStream>,
     }
@@ -77,6 +89,11 @@ impl TcpStream {
     ///     Ok(())
     /// }
     /// ```
+    ///
+    /// The [`write_all`] method is defined on the [`AsyncWriteExt`] trait.
+    ///
+    /// [`write_all`]: fn@crate::io::AsyncWriteExt::write_all
+    /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
     pub async fn connect<A: ToSocketAddrs>(addr: A) -> io::Result<TcpStream> {
         let addrs = addr.to_socket_addrs().await?;
 
@@ -303,6 +320,11 @@ impl TcpStream {
     ///     Ok(())
     /// }
     /// ```
+    ///
+    /// The [`read`] method is defined on the [`AsyncReadExt`] trait.
+    ///
+    /// [`read`]: fn@crate::io::AsyncReadExt::read
+    /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
     pub async fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         poll_fn(|cx| self.poll_peek(cx, buf)).await
     }