termio: update docs

1 files changed, 18 insertions, 3 deletions

diff --git a/src/termio.zig b/src/termio.zig
index 2be1e1dbb..b4943cca9 100644
--- a/src/termio.zig
+++ b/src/termio.zig
@@ -1,6 +1,21 @@
-//! IO implementation and utilities. The IO implementation is responsible
-//! for taking the config, spinning up a child process, and handling IO
-//! with the terminal.
+//! Termio is responsible for "terminal IO." Specifically, this is the
+//! reading and writing of bytes for the underlying pty or pty-like device.
+//!
+//! Termio is constructed of a few components:
+//!   - Termio - The main shared struct that has common logic across all
+//!     backends and mailboxes (defined below).
+//!   - Backend - Responsible for the actual physical IO. For example, one
+//!     implementation creates a subprocess, allocates and assigns a pty,
+//!     and sets up a read thread on the pty.
+//!   - Mailbox - Responsible for storing/dispensing event messages to
+//!     the backend. This exists separately from backends because termio
+//!     is built to be both single and multi-threaded.
+//!
+//! Termio supports (and recommends) multi-threaded operation. Multi-threading
+//! enables the read/writes to generally happen on separate threads and
+//! almost always improves throughput and latency under heavy IO load. To
+//! enable threading, use the Thread struct. This wraps a Termio, requires
+//! specific backend/mailbox capabilities, and sets up the necessary threads.
 
 const stream_handler = @import("termio/stream_handler.zig");