doc: add API documentation

1 files changed, 26 insertions, 3 deletions

diff --git a/ttwhy/terminal/scoped_attributes.cppm b/ttwhy/terminal/scoped_attributes.cppm
index 2ca34a3..56fbe58 100644
--- a/ttwhy/terminal/scoped_attributes.cppm
+++ b/ttwhy/terminal/scoped_attributes.cppm
@@ -52,9 +52,12 @@ namespace ttwhy::terminal
     }
   }
 
-  //! Store the current TC attributes and restore them on destruction.
+  //! RAII wrapper storing the current terminal attributes and restoring them on destruction.
   export struct scoped_attributes
   {
+    //! Construct and capture the current attributes of a terminal file descriptor.
+    //!
+    //! @param file_descriptor The file descriptor of the terminal.
     explicit scoped_attributes(int file_descriptor)
         : m_file_descriptor{-1}
         , m_attributes{}
@@ -91,36 +94,56 @@ namespace ttwhy::terminal
       return *this;
     }
 
-    //! Check if canonical mode is currently active
+    //! Check if canonical mode is currently active.
+    //!
+    //! @return True if ICANON is set, false otherwise.
     [[nodiscard]] auto canonical_mode() const noexcept -> bool
     {
       return get_line_discipline_flag(m_file_descriptor, ICANON);
     }
 
-    //! Set whether canonical mode is active or not.
+    //! Set whether canonical mode is active or not on an lvalue reference.
+    //!
+    //! @param enabled True to enable canonical mode, false to disable.
+    //! @return Reference to this object for chaining.
     auto canonical_mode(bool enabled) & -> scoped_attributes &
     {
       set_line_discipline_flag(m_file_descriptor, ICANON, enabled);
       return *this;
     }
 
+    //! Set whether canonical mode is active or not on an rvalue.
+    //!
+    //! @param enabled True to enable canonical mode, false to disable.
+    //! @return The modified scoped_attributes object by value.
     auto canonical_mode(bool enabled) && -> scoped_attributes
     {
       set_line_discipline_flag(m_file_descriptor, ICANON, enabled);
       return std::move(*this);
     }
 
+    //! Check if echo is currently active.
+    //!
+    //! @return True if ECHO is set, false otherwise.
     [[nodiscard]] auto echo() const noexcept -> bool
     {
       return get_line_discipline_flag(m_file_descriptor, ECHO);
     }
 
+    //! Set whether echo is active or not on an lvalue reference.
+    //!
+    //! @param enabled True to enable echo, false to disable.
+    //! @return Reference to this object for chaining.
     auto echo(bool enabled) & -> scoped_attributes &
     {
       set_line_discipline_flag(m_file_descriptor, ECHO, enabled);
       return *this;
     }
 
+    //! Set whether echo is active or not on an rvalue.
+    //!
+    //! @param enabled True to enable echo, false to disable.
+    //! @return The modified scoped_attributes object by value.
     auto echo(bool enabled) && -> scoped_attributes
     {
       set_line_discipline_flag(m_file_descriptor, ECHO, enabled);