x86_64: vga: add documentation for text mode API

1 files changed, 58 insertions, 20 deletions

diff --git a/source/arch/x86_64/include/arch/video/vga/text.hpp b/source/arch/x86_64/include/arch/video/vga/text.hpp
index c9a79b8..c8ff162 100644
--- a/source/arch/x86_64/include/arch/video/vga/text.hpp
+++ b/source/arch/x86_64/include/arch/video/vga/text.hpp
@@ -6,30 +6,48 @@
 
 namespace teachos::arch::video::vga::text
 {
+  /**
+   * @brief The colors available in the standard VGA text mode.
+   */
   enum struct color : std::uint8_t
   {
-    black,
-    blue,
-    green,
-    cyan,
-    red,
-    purple,
-    brown,
-    gray,
+    black,  /**< #000000 */
+    blue,   /**< #0000AA */
+    green,  /**< #00AA00 */
+    cyan,   /**< #00AAAA */
+    red,    /**< #AA0000 */
+    purple, /**< #AA00AA */
+    brown,  /**< #AA5500 */
+    gray,   /**< #AAAAAA */
   };
 
+  /**
+   * @brief The foreground color modification flag.
+   */
   enum struct foreground_flag : bool
   {
-    none,
-    intense,
+    none,    /**< Apply no flag e.g., keep color as is. */
+    intense, /**< Make the color more intense (usually brighter). */
   };
 
+  /**
+   * @brief The background color modification flag.
+   */
   enum struct background_flag : bool
   {
-    none,
-    blink_or_bright,
+    none,            /**< Apply no flag e.g., keep color as is. */
+    blink_or_bright, /**< Make the cell blink or more intense, dependent on the VGA configuration */
   };
 
+  /**
+   * @brief The VGA text mode attribute.
+   *
+   * In the text mode of VGA, every code point being presented is followed by an attribute description. This allows for
+   * the modification of how the relevant "cell" is presented.
+   *
+   * @see vga::text::foreground_flag
+   * @see vga::text::background_flag
+   */
   struct attribute
   {
     color foreground_color : 3;
@@ -38,21 +56,41 @@ namespace teachos::arch::video::vga::text
     enum background_flag background_flag : 1;
   };
 
-  static_assert(sizeof(attribute) == 1);
+  static_assert(sizeof(attribute) == 1, "The VGA text mode attribute must fit inside a single byte.");
 
+  /**
+   * @brief Commonly used VGA text mode attributes
+   */
   namespace common_attributes
   {
-    [[maybe_unused]]
-    auto constexpr gray_on_black = attribute{color::gray, foreground_flag::none, color::black, background_flag::none};
+    [[maybe_unused]] auto constexpr gray_on_black =
+        attribute{color::gray, foreground_flag::none, color::black, background_flag::none};
 
-    [[maybe_unused]]
-    auto constexpr green_on_black = attribute{color::green, foreground_flag::none, color::black, background_flag::none};
+    [[maybe_unused]] auto constexpr green_on_black =
+        attribute{color::green, foreground_flag::none, color::black, background_flag::none};
 
-    [[maybe_unused]]
-    auto constexpr white_on_red = attribute{color::gray, foreground_flag::intense, color::red, background_flag::none};
-  }
+    [[maybe_unused]] auto constexpr white_on_red =
+        attribute{color::gray, foreground_flag::intense, color::red, background_flag::none};
+  }  // namespace common_attributes
 
+  /**
+   * @brief Clear the VGA text mode buffer.
+   *
+   * @note This function also resets the text mode buffer pointer.
+   * 
+   * @param attribute The attribute to "clear" the screen with.
+   */
   auto clear(attribute attribute = common_attributes::gray_on_black) -> void;
+
+  /**
+   * @brief Write a string of code points to the VGA text buffer.
+   * 
+   * @note This function also updates the text mode buffer pointer.
+   * 
+   * @param code_points A string of (8-bit) code points to write to the VGA text mode buffer.
+   * @param attribute The attribute to apply to the written sequence of code points.
+   * @see vga::text::attribute
+   */
   auto write(std::string_view code_points, attribute attribute) -> void;
 }  // namespace teachos::arch::video::vga::text