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

Refs: #2307

5 files changed, 128 insertions, 13 deletions

diff --git a/tokio/src/fs/file.rs b/tokio/src/fs/file.rs
index a1f22fc9..cc4a187d 100644
--- a/tokio/src/fs/file.rs
+++ b/tokio/src/fs/file.rs
@@ -24,12 +24,28 @@ use std::task::Poll::*;
 /// Tokio runtime.
 ///
 /// An instance of a `File` can be read and/or written depending on what options
-/// it was opened with. Files also implement Seek to alter the logical cursor
-/// that the file contains internally.
+/// it was opened with. Files also implement [`AsyncSeek`] to alter the logical
+/// cursor that the file contains internally.
 ///
-/// Files are automatically closed when they go out of scope.
+/// A file will not be closed immediately when it goes out of scope if there
+/// are any IO operations that have not yet completed. To ensure that a file is
+/// closed immediately when it is dropped, you should call [`flush`] before
+/// dropping it. Note that this does not ensure that the file has been fully
+/// written to disk; the operating system might keep the changes around in an
+/// in-memory buffer. See the [`sync_all`] method for telling the OS to write
+/// the data to disk.
 ///
-/// [std]: std::fs::File
+/// Reading and writing to a `File` is usually done using the convenience
+/// methods found on the [`AsyncReadExt`] and [`AsyncWriteExt`] traits. Examples
+/// import these traits through [the prelude].
+///
+/// [std]: struct@std::fs::File
+/// [`AsyncSeek`]: trait@crate::io::AsyncSeek
+/// [`flush`]: fn@crate::io::AsyncWriteExt::flush
+/// [`sync_all`]: fn@crate::fs::File::sync_all
+/// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
+/// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt
+/// [the prelude]: crate::prelude
 ///
 /// # Examples
 ///
@@ -37,7 +53,7 @@ use std::task::Poll::*;
 ///
 /// ```no_run
 /// use tokio::fs::File;
-/// use tokio::prelude::*;
+/// use tokio::prelude::*; // for write_all()
 ///
 /// # async fn dox() -> std::io::Result<()> {
 /// let mut file = File::create("foo.txt").await?;
@@ -50,7 +66,7 @@ use std::task::Poll::*;
 ///
 /// ```no_run
 /// use tokio::fs::File;
-/// use tokio::prelude::*;
+/// use tokio::prelude::*; // for read_to_end()
 ///
 /// # async fn dox() -> std::io::Result<()> {
 /// let mut file = File::open("foo.txt").await?;
@@ -114,6 +130,11 @@ impl File {
     /// # Ok(())
     /// # }
     /// ```
+    ///
+    /// The [`read_to_end`] method is defined on the [`AsyncReadExt`] trait.
+    ///
+    /// [`read_to_end`]: fn@crate::io::AsyncReadExt::read_to_end
+    /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
     pub async fn open(path: impl AsRef<Path>) -> io::Result<File> {
         let path = path.as_ref().to_owned();
         let std = asyncify(|| sys::File::open(path)).await?;
@@ -149,6 +170,11 @@ impl File {
     /// # 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 create(path: impl AsRef<Path>) -> io::Result<File> {
         let path = path.as_ref().to_owned();
         let std_file = asyncify(move || sys::File::create(path)).await?;
@@ -195,6 +221,11 @@ impl File {
     /// # Ok(())
     /// # }
     /// ```
+    ///
+    /// The [`read_exact`] method is defined on the [`AsyncReadExt`] trait.
+    ///
+    /// [`read_exact`]: fn@crate::io::AsyncReadExt::read_exact
+    /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt
     pub async fn seek(&mut self, mut pos: SeekFrom) -> io::Result<u64> {
         self.complete_inflight().await;
 
@@ -251,6 +282,11 @@ impl File {
     /// # 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 sync_all(&mut self) -> io::Result<()> {
         self.complete_inflight().await;
 
@@ -280,6 +316,11 @@ impl File {
     /// # 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 sync_data(&mut self) -> io::Result<()> {
         self.complete_inflight().await;
 
@@ -312,6 +353,11 @@ impl File {
     /// # 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 set_len(&mut self, size: u64) -> io::Result<()> {
         self.complete_inflight().await;
 
diff --git a/tokio/src/io/util/async_seek_ext.rs b/tokio/src/io/util/async_seek_ext.rs
index c7243c7f..c7a0f72f 100644
--- a/tokio/src/io/util/async_seek_ext.rs
+++ b/tokio/src/io/util/async_seek_ext.rs
@@ -2,7 +2,9 @@ use crate::io::seek::{seek, Seek};
 use crate::io::AsyncSeek;
 use std::io::SeekFrom;
 
-/// An extension trait which adds utility methods to `AsyncSeek` types.
+/// An extension trait which adds utility methods to [`AsyncSeek`] types.
+///
+/// As a convenience, this trait may be imported using the [`prelude`]:
 ///
 /// # Examples
 ///
@@ -25,6 +27,11 @@ use std::io::SeekFrom;
 ///     Ok(())
 /// }
 /// ```
+///
+/// See [module][crate::io] documentation for more details.
+///
+/// [`AsyncSeek`]: AsyncSeek
+/// [`prelude`]: crate::prelude
 pub trait AsyncSeekExt: AsyncSeek {
     /// Creates a future which will seek an IO object, and then yield the
     /// new position in the object and the object itself.
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
     }