docs: improve tokio::io API documentation (#1815)

Adds method level documentation for `tokio::io`.

examples/proxy.rs

@@ -22,12 +22,13 @@
 
 #![warn(rust_2018_idioms)]
 
-use futures::{future::try_join, FutureExt};
-use std::{env, error::Error};
-use tokio::{
-    io::AsyncReadExt,
-    net::{TcpListener, TcpStream},
-};
+use tokio::io;
+use tokio::net::{TcpListener, TcpStream};
+
+use futures::future::try_join;
+use futures::FutureExt;
+use std::env;
+use std::error::Error;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
@@ -58,8 +59,8 @@ async fn transfer(mut inbound: TcpStream, proxy_addr: String) -> Result<(), Box<
     let (mut ri, mut wi) = inbound.split();
     let (mut ro, mut wo) = outbound.split();
 
-    let client_to_server = ri.copy(&mut wo);
-    let server_to_client = ro.copy(&mut wi);
+    let client_to_server = io::copy(&mut ri, &mut wo);
+    let server_to_client = io::copy(&mut ro, &mut wi);
 
     try_join(client_to_server, server_to_client).await?;
 

tokio/src/io/async_read.rs

@@ -5,11 +5,13 @@ use std::ops::DerefMut;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-/// Read bytes asynchronously.
+/// Read bytes from a source.
 ///
-/// This trait inherits from `std::io::Read` and indicates that an I/O object is
-/// **non-blocking**. All non-blocking I/O objects must return an error when
-/// bytes are unavailable instead of blocking the current thread.
+/// This trait is analogous to the [`std::io::Read`] trait, but integrates with
+/// the asynchronous task system. In particular, the [`poll_read`] method,
+/// unlike [`Read::read`], will automatically queue the current task for wakeup
+/// and return if data is not yet available, rather than blocking the calling
+/// thread.
 ///
 /// Specifically, this means that the `poll_read` function will return one of
 /// the following:
@@ -30,6 +32,14 @@ use std::task::{Context, Poll};
 ///
 /// This trait importantly means that the `read` method only works in the
 /// context of a future's task. The object may panic if used outside of a task.
+///
+/// Utilities for working with `AsyncRead` values are provided by
+/// [`AsyncReadExt`].
+///
+/// [`poll_read`]: AsyncRead::poll_read
+/// [`std::io::Read`]: std::io::Read
+/// [`Read::read`]: std::io::Read::read
+/// [`AsyncReadExt`]: crate::io::AsyncReadExt
 pub trait AsyncRead {
     /// Prepares an uninitialized buffer to be safe to pass to `read`. Returns
     /// `true` if the supplied buffer was zeroed out.

tokio/src/io/mod.rs

@@ -1,6 +1,6 @@
 #![cfg_attr(loom, allow(dead_code, unreachable_pub))]
 
-//! Asynchronous I/O.
+//! Traits, helpers, and type definitions for asynchronous I/O functionality.
 //!
 //! This module is the asynchronous version of `std::io`. Primarily, it
 //! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which are asynchronous
@@ -15,7 +15,19 @@
 //! type will _yield_ to the Tokio scheduler when IO is not ready, rather than
 //! blocking. This allows other tasks to run while waiting on IO.
 //!
-//! In asynchronous programs, Tokio's [`AsyncRead`] and [`AsyncWrite`] traits
+//! Another difference is that [`AsyncRead`] and [`AsyncWrite`] only contain
+//! core methods needed to provide asynchronous reading and writing
+//! functionality. Instead, utility methods are defined in the [`AsyncReadExt`]
+//! and [`AsyncWriteExt`] extension traits. These traits are automatically
+//! implemented for all values that implement [`AsyncRead`] and [`AsyncWrite`]
+//! respectively.
+//!
+//! End users will rarely interact directly with [`AsyncRead`] and
+//! [`AsyncWrite`]. Instead, they will use the async functions defined in the
+//! extension traits. Library authors are expected to implement [`AsyncRead`]
+//! and [`AsyncWrite`] in order to provide types that behave like byte streams.
+//!
+//! Even with these differences, Tokio's [`AsyncRead`] and [`AsyncWrite`] traits
 //! can be used in almost exactly the same manner as the standard library's
 //! `Read` and `Write`. Most types in the standard library that implement `Read`
 //! and `Write` have asynchronous equivalents in `tokio` that implement
@@ -26,8 +38,7 @@
 //! can do the same with [`tokio::fs::File`][`File`]:
 //!
 //! ```no_run
-//! use tokio::io;
-//! use tokio::prelude::*;
+//! use tokio::io::{self, AsyncReadExt};
 //! use tokio::fs::File;
 //!
 //! #[tokio::main]
@@ -64,10 +75,8 @@
 //! extra methods to any async reader:
 //!
 //! ```no_run
-//! use tokio::io;
-//! use tokio::io::BufReader;
+//! use tokio::io::{self, BufReader, AsyncBufReadExt};
 //! use tokio::fs::File;
-//! use tokio::prelude::*;
 //!
 //! #[tokio::main]
 //! async fn main() -> io::Result<()> {
@@ -87,10 +96,8 @@
 //! to [`write`](crate::io::AsyncWriteExt::write):
 //!
 //! ```no_run
-//! use tokio::io;
-//! use tokio::io::BufWriter;
+//! use tokio::io::{self, BufWriter, AsyncWriteExt};
 //! use tokio::fs::File;
-//! use tokio::prelude::*;
 //!
 //! #[tokio::main]
 //! async fn main() -> io::Result<()> {