doc: add API documentation

1 files changed, 12 insertions, 0 deletions

diff --git a/ttwhy/terminal/readers.cppm b/ttwhy/terminal/readers.cppm
index ffa5687..c59f30b 100644
--- a/ttwhy/terminal/readers.cppm
+++ b/ttwhy/terminal/readers.cppm
@@ -18,6 +18,18 @@ import ttwhy.core;
 namespace ttwhy::terminal
 {
 
+  //! Asynchronously read raw bytes from an input stream, decode terminal events, and dispatch them to a router.
+  //!
+  //! Reads chunks from the input stream, feeding them to a terminal scanner configured with the specified
+  //! policy. If a sequence is pending and no data arrives before the inter-byte timeout, triggers a timeout
+  //! resolution. Dispatches all resulting events to the provided router.
+  //!
+  //! @tparam TerminalPolicy The terminal escape decoding policy (defaults to xterm_policy).
+  //! @tparam InputStream The input stream type supporting asynchronous reads.
+  //! @tparam AppRouter The router type that processes terminal input events.
+  //! @param stream The input stream descriptor to read from.
+  //! @param router The application router to receive and process input events.
+  //! @return An awaitable task that runs until the stream ends or encounters an error.
   export template<typename TerminalPolicy = xterm_policy, typename InputStream, ttwhy::router<input_event> AppRouter>
   auto read_events(InputStream & stream, AppRouter & router) -> asio::awaitable<void>
   {