doc: add API documentation

1 files changed, 44 insertions, 0 deletions

diff --git a/ttwhy/terminal/events.cppm b/ttwhy/terminal/events.cppm
index 93b2326..ce4a7d5 100644
--- a/ttwhy/terminal/events.cppm
+++ b/ttwhy/terminal/events.cppm
@@ -10,6 +10,7 @@ import ttwhy.core;
 
 export namespace ttwhy::terminal
 {
+  //! Represents standard C0 terminal control keys.
   enum struct control_key : std::uint8_t
   {
     enter,
@@ -18,6 +19,7 @@ export namespace ttwhy::terminal
     backspace,
   };
 
+  //! Represents terminal cursor and keypad navigation keys.
   enum struct navigation_key : std::uint8_t
   {
     up,
@@ -32,6 +34,7 @@ export namespace ttwhy::terminal
     page_down,
   };
 
+  //! Represents individual keyboard modifier keys.
   enum struct modifier : std::uint8_t
   {
     none = 0,
@@ -41,65 +44,106 @@ export namespace ttwhy::terminal
     meta = 8,
   };
 
+  //! Represents a bitmask combination of keyboard modifiers.
   enum struct modifier_set : std::uint8_t
   {
   };
 
+  //! Combine two keyboard modifiers into a modifier set.
+  //!
+  //! @param lhs The first modifier to combine.
+  //! @param rhs The second modifier to combine.
+  //! @return A modifier set containing both modifiers.
   constexpr auto operator|(modifier lhs, modifier rhs) -> modifier_set
   {
     return static_cast<modifier_set>(std::to_underlying(lhs) | std::to_underlying(rhs));
   }
 
+  //! Add a keyboard modifier to an existing modifier set.
+  //!
+  //! @param lhs The existing modifier set.
+  //! @param rhs The modifier to add.
+  //! @return The resulting modifier set.
   constexpr auto operator|(modifier_set lhs, modifier rhs) -> modifier_set
   {
     return static_cast<modifier_set>(std::to_underlying(lhs) | std::to_underlying(rhs));
   }
 
+  //! Compute the bitwise intersection of two keyboard modifiers.
+  //!
+  //! @param lhs The first modifier.
+  //! @param rhs The second modifier.
+  //! @return The intersection as a modifier set.
   constexpr auto operator&(modifier lhs, modifier rhs) -> modifier_set
   {
     return static_cast<modifier_set>(std::to_underlying(lhs) & std::to_underlying(rhs));
   }
 
+  //! Check for the presence of a keyboard modifier in a modifier set.
+  //!
+  //! @param lhs The modifier set.
+  //! @param rhs The modifier to test.
+  //! @return The intersection as a modifier set.
   constexpr auto operator&(modifier_set lhs, modifier rhs) -> modifier_set
   {
     return static_cast<modifier_set>(std::to_underlying(lhs) & std::to_underlying(rhs));
   }
 
+  //! Check whether all specified modifiers are present in a modifier set.
+  //!
+  //! @tparam Modifier The modifier types to check.
+  //! @param mask The modifier set to inspect.
+  //! @param flag The modifier flags that must all be present.
+  //! @return True if all specified flags are present, false otherwise.
   template<std::same_as<modifier>... Modifier>
   constexpr auto has_all(modifier_set mask, Modifier... flag) -> bool
   {
     return (true && ... && (mask & flag));
   }
 
+  //! Check whether any of the specified modifiers are present in a modifier set.
+  //!
+  //! @tparam Modifier The modifier types to check.
+  //! @param mask The modifier set to inspect.
+  //! @param flag The modifier flags to test for.
+  //! @return True if at least one of the specified flags is present, false otherwise.
   template<std::same_as<modifier>... Modifier>
   constexpr auto has_any(modifier_set mask, Modifier... flag) -> bool
   {
     return (false || ... || (mask & flag));
   }
 
+  //! Represents a printable ASCII or raw character event.
   struct character_event
   {
     char value{};
   };
 
+  //! Represents a terminal control key event.
   struct control_event
   {
     control_key key{};
   };
 
+  //! Represents a terminal cursor or keypad navigation event.
   struct navigation_event
   {
     navigation_key key{};
     modifier_set modifiers{};
   };
 
+  //! Represents a Control-key chord event.
   struct ctrl_chord_event
   {
     char key{};
   };
 
+  //! Variant representing any input event produced by a terminal scanner.
   using input_event = std::variant<character_event, control_event, navigation_event, ctrl_chord_event>;
 
+  //! Validates that a sink can receive all terminal input event types.
+  //!
+  //! @tparam Sink The sink callable type to validate.
   template<typename Sink>
   concept event_sink = ttwhy::event_sink<Sink, character_event> && ttwhy::event_sink<Sink, control_event> &&
                        ttwhy::event_sink<Sink, navigation_event>;