docs(rt/tokio): document io adaptors

Signed-off-by: katelyn martin <me+cratelyn@katelyn.world>

Author: cratelyn

src/rt/tokio.rs

@@ -1,4 +1,56 @@
-//! Tokio IO integration for hyper
+//! [`tokio`] runtime components integration for [`hyper`].
+//!
+//! [`hyper::rt`] exposes a set of traits to allow hyper to be agnostic to
+//! its underlying asynchronous runtime. This submodule provides glue for
+//! [`tokio`] users to bridge those types to [`hyper`]'s interfaces.
+//!
+//! # IO
+//!
+//! [`hyper`] abstracts over asynchronous readers and writers using [`Read`]
+//! and [`Write`], while [`tokio`] abstracts over this using [`AsyncRead`]
+//! and [`AsyncWrite`]. This submodule provides a collection of IO adaptors
+//! to bridge these two IO ecosystems together: [`TokioIo<I>`],
+//! [`WithHyperIo<I>`], and [`WithTokioIo<I>`].
+//!
+//! To compare and constrast these IO adaptors and to help explain which
+//! is the proper choice for your needs, here is a table showing which IO
+//! traits these implement, given two types `T` and `H` which implement
+//! Tokio's and Hyper's corresponding IO traits:
+//!
+//! |                    | [`AsyncRead`]    | [`AsyncWrite`]    | [`Read`]     | [`Write`]    |
+//! |--------------------|------------------|-------------------|--------------|--------------|
+//! | `T`                | ✅ **true**      | ✅ **true**       | ❌ **false** | ❌ **false** |
+//! | `H`                | ❌ **false**     | ❌ **false**      | ✅ **true**  | ✅ **true**  |
+//! | [`TokioIo<T>`]     | ❌ **false**     | ❌ **false**      | ✅ **true**  | ✅ **true**  |
+//! | [`TokioIo<H>`]     | ✅ **true**      | ✅ **true**       | ❌ **false** | ❌ **false** |
+//! | [`WithHyperIo<T>`] | ✅ **true**      | ✅ **true**       | ✅ **true**  | ✅ **true**  |
+//! | [`WithHyperIo<H>`] | ❌ **false**     | ❌ **false**      | ❌ **false** | ❌ **false** |
+//! | [`WithTokioIo<T>`] | ❌ **false**     | ❌ **false**      | ❌ **false** | ❌ **false** |
+//! | [`WithTokioIo<H>`] | ✅ **true**      | ✅ **true**       | ✅ **true**  | ✅ **true**  |
+//!
+//! For most situations, [`TokioIo<I>`] is the proper choice. This should be
+//! constructed, wrapping some underlying [`hyper`] or [`tokio`] IO, at the
+//! call-site of a function like [`hyper::client::conn::http1::handshake`].
+//!
+//! [`TokioIo<I>`] switches across these ecosystems, but notably does not
+//! preserve the existing IO trait implementations of its underlying IO. If
+//! one wishes to _extend_ IO with additional implementations,
+//! [`WithHyperIo<I>`] and [`WithTokioIo<I>`] are the correct choice.
+//!
+//! For example, a Tokio reader/writer can be wrapped in [`WithHyperIo<I>`].
+//! That will implement _both_ sets of IO traits. Conversely,
+//! [`WithTokioIo<I>`] will implement both sets of IO traits given a
+//! reader/writer that implements Hyper's [`Read`] and [`Write`].
+//!
+//! See [`tokio::io`] and ["_Asynchronous IO_"][tokio-async-docs] for more
+//! information.
+//!
+//! [`AsyncRead`]: tokio::io::AsyncRead
+//! [`AsyncWrite`]: tokio::io::AsyncWrite
+//! [`Read`]: hyper::rt::Read
+//! [`Write`]: hyper::rt::Write
+//! [tokio-async-docs]: https://docs.rs/tokio/latest/tokio/#asynchronous-io
+
 use std::{
     future::Future,
     pin::Pin,