doc: add API documentation

1 files changed, 31 insertions, 0 deletions

diff --git a/ttwhy/terminal/policies.cppm b/ttwhy/terminal/policies.cppm
index acf9371..83694b8 100644
--- a/ttwhy/terminal/policies.cppm
+++ b/ttwhy/terminal/policies.cppm
@@ -58,8 +58,13 @@ namespace ttwhy::terminal
 
   }  // namespace detail
 
+  //! Policy for decoding standard ANSI/VT escape sequences.
   export struct ansi_policy
   {
+    //! Resolve a VT220 keypad sequence and emit the corresponding navigation event.
+    //!
+    //! @param buffer The CSI parameter buffer.
+    //! @param sink The event sink to receive the resolved navigation event.
     constexpr auto static resolve_vt220_keypad(std::string & buffer, event_sink auto & sink) -> void
     {
       if (buffer.empty())
@@ -74,6 +79,10 @@ namespace ttwhy::terminal
       buffer.clear();
     }
 
+    //! Resolve a VT100 cursor sequence and emit the corresponding navigation event.
+    //!
+    //! @param terminator The CSI terminator character indicating direction or key.
+    //! @param sink The event sink to receive the resolved navigation event.
     constexpr auto static resolve_vt100_cursor(char terminator, std::string &, event_sink auto & sink) -> void
     {
       if (auto key = detail::map_vt100_cursor(terminator))
@@ -82,6 +91,10 @@ namespace ttwhy::terminal
       }
     }
 
+    //! Resolve an SS3 single-shift sequence and emit the corresponding navigation event.
+    //!
+    //! @param terminator The SS3 terminator character indicating direction or key.
+    //! @param sink The event sink to receive the resolved navigation event.
     constexpr auto static resolve_ss3(char terminator, event_sink auto & sink) -> void
     {
       if (auto key = detail::map_vt100_cursor(terminator))
@@ -91,8 +104,13 @@ namespace ttwhy::terminal
     }
   };
 
+  //! Policy for decoding xterm escape sequences, including modifier parameters.
   export struct xterm_policy
   {
+    //! Parse keyboard modifier parameters from a CSI parameter buffer.
+    //!
+    //! @param buffer The CSI parameter buffer string view.
+    //! @return The parsed modifier set, or empty if none present.
     constexpr auto static parse_modifiers(std::string_view buffer) -> modifier_set
     {
       auto delimiter = buffer.find(';');
@@ -120,6 +138,10 @@ namespace ttwhy::terminal
       return static_cast<modifier_set>(modifier_value - 1);
     }
 
+    //! Resolve a VT220 keypad sequence with modifiers and emit the navigation event.
+    //!
+    //! @param buffer The CSI parameter buffer containing key and modifier values.
+    //! @param sink The event sink to receive the resolved navigation event.
     constexpr auto static resolve_vt220_keypad(std::string & buffer, event_sink auto & sink) -> void
     {
       if (buffer.empty())
@@ -136,6 +158,11 @@ namespace ttwhy::terminal
       buffer.clear();
     }
 
+    //! Resolve a VT100 cursor sequence with modifiers and emit the navigation event.
+    //!
+    //! @param terminator The CSI terminator character indicating direction or key.
+    //! @param buffer The CSI parameter buffer containing modifier values.
+    //! @param sink The event sink to receive the resolved navigation event.
     constexpr auto static resolve_vt100_cursor(char terminator, std::string & buffer, event_sink auto & sink) -> void
     {
       auto modifiers = parse_modifiers(buffer);
@@ -146,6 +173,10 @@ namespace ttwhy::terminal
       }
     }
 
+    //! Resolve an SS3 single-shift sequence and emit the corresponding navigation event.
+    //!
+    //! @param terminator The SS3 terminator character indicating direction or key.
+    //! @param sink The event sink to receive the resolved navigation event.
     constexpr auto static resolve_ss3(char terminator, event_sink auto & sink) -> void
     {
       if (auto key = detail::map_vt100_cursor(terminator))