From 79a35574ce6d472f7a7cc4a200a1ed7befe34066 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@gmail.com>
Date: Thu, 24 Sep 2026 07:59:43 +0200
Subject: doc: add API documentation

---
 ttwhy/terminal/scanner.cppm | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'ttwhy/terminal/scanner.cppm')

diff --git a/ttwhy/terminal/scanner.cppm b/ttwhy/terminal/scanner.cppm
index 8a722b4..f1540f2 100644
--- a/ttwhy/terminal/scanner.cppm
+++ b/ttwhy/terminal/scanner.cppm
@@ -200,23 +200,37 @@ namespace ttwhy::terminal::detail
 export namespace ttwhy::terminal
 {
 
+  //! State machine tokenizer that decodes terminal escape sequences into input events.
+  //!
+  //! @tparam Sink The event sink callable type.
+  //! @tparam TerminalPolicy The terminal escape policy.
   template<event_sink Sink, typename TerminalPolicy>
   struct scanner
   {
+    //! Construct a terminal scanner bound to an event sink.
+    //!
+    //! @param sink The event sink to deliver decoded input events to.
     explicit scanner(Sink & sink)
         : m_state_machine{sink, m_csi_buffer}
     {}
 
+    //! Process a buffer of incoming raw bytes through the state machine.
+    //!
+    //! @param buffer The view of raw bytes to decode.
     auto process(std::span<char const> buffer) -> void
     {
       std::ranges::for_each(buffer, [&](auto byte) { m_state_machine.process_event(detail::byte_received{byte}); });
     }
 
+    //! Notify the state machine that an inter-byte timeout expired.
     auto timeout()
     {
       m_state_machine.process_event(detail::timeout_expired{});
     }
 
+    //! Check if an escape sequence is currently pending completion.
+    //!
+    //! @return True if a sequence is incomplete, false otherwise.
     [[nodiscard]] auto is_pending() const -> bool
     {
       return m_state_machine.is(detail::escape_sequence) ||  //
@@ -230,6 +244,9 @@ export namespace ttwhy::terminal
         m_state_machine;
   };
 
+  //! Convenience alias for a terminal scanner configured with the ANSI policy.
+  //!
+  //! @tparam Sink The event sink callable type.
   template<event_sink Sink>
   using ansi = scanner<Sink, ansi_policy>;
 
-- 
cgit v1.2.3