From f61858725e92d3e77eb8a826a50497045ce67c41 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Tue, 17 Oct 2023 14:52:17 +0200
Subject: doc: introduce basic documentation structure

---
 source/arch/x86_64/include/arch/io/port_io.hpp     |  3 ++
 source/arch/x86_64/include/arch/video/vga/io.hpp   | 14 +++++++++
 source/arch/x86_64/include/arch/video/vga/text.hpp | 33 ++++++++++++++--------
 3 files changed, 38 insertions(+), 12 deletions(-)

(limited to 'source')

diff --git a/source/arch/x86_64/include/arch/io/port_io.hpp b/source/arch/x86_64/include/arch/io/port_io.hpp
index 736893c..5b61f90 100644
--- a/source/arch/x86_64/include/arch/io/port_io.hpp
+++ b/source/arch/x86_64/include/arch/io/port_io.hpp
@@ -20,6 +20,9 @@ namespace teachos::arch::io
   {
     static_assert(Size == 1 || Size == 2 || Size == 4, "A port must be either 1, 2, or 4 bytes in size");
 
+    /**
+     * @brief The type of data available for reading and writing through this port.
+     */
     using io_type =
         std::conditional_t<Size == 1, std::byte, std::conditional_t<Size == 2, std::uint16_t, std::uint32_t>>;
 
diff --git a/source/arch/x86_64/include/arch/video/vga/io.hpp b/source/arch/x86_64/include/arch/video/vga/io.hpp
index af77998..9226c5c 100644
--- a/source/arch/x86_64/include/arch/video/vga/io.hpp
+++ b/source/arch/x86_64/include/arch/video/vga/io.hpp
@@ -11,12 +11,26 @@ namespace teachos::arch::video::vga
   namespace crtc
   {
 
+    /**
+     * @brief The address port of the CRT Controller
+     */
     using address_port = arch::io::port<0x3d4, 1>;
+
+    /**
+     * @brief The data port of the CRT Controller
+     */
     using data_port = arch::io::port<0x3d5, 1>;
 
     namespace registers
     {
+      /**
+       * @brief The address of the Cursor Start register of the CRTC
+       */
       [[maybe_unused]] auto constexpr cursor_start = std::byte{0x0a};
+
+      /**
+       * @brief The address of the Cursor End register of the CRTC
+       */
       [[maybe_unused]] auto constexpr curser_end = std::byte{0x0b};
     }  // namespace registers
 
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 e615eba..1e584d6 100644
--- a/source/arch/x86_64/include/arch/video/vga/text.hpp
+++ b/source/arch/x86_64/include/arch/video/vga/text.hpp
@@ -11,14 +11,14 @@ namespace teachos::arch::video::vga::text
    */
   enum struct color : std::uint8_t
   {
-    black,  /**< #000000 */
-    blue,   /**< #0000AA */
-    green,  /**< #00AA00 */
-    cyan,   /**< #00AAAA */
-    red,    /**< #AA0000 */
-    purple, /**< #AA00AA */
-    brown,  /**< #AA5500 */
-    gray,   /**< #AAAAAA */
+    black,  /**< Equivalent to HTML color \#000000 */
+    blue,   /**< Equivalent to HTML color \#0000AA */
+    green,  /**< Equivalent to HTML color \#00AA00 */
+    cyan,   /**< Equivalent to HTML color \#00AAAA */
+    red,    /**< Equivalent to HTML color \#AA0000 */
+    purple, /**< Equivalent to HTML color \#AA00AA */
+    brown,  /**< Equivalent to HTML color \#AA5500 */
+    gray,   /**< Equivalent to HTML color \#AAAAAA */
   };
 
   /**
@@ -50,10 +50,10 @@ namespace teachos::arch::video::vga::text
    */
   struct attribute
   {
-    color foreground_color : 3;
-    enum foreground_flag foreground_flag : 1;
-    color bacground_color : 3;
-    enum background_flag background_flag : 1;
+    color foreground_color : 3;               /**< The foreground color of the cell, e.g. the color of the code point.*/
+    enum foreground_flag foreground_flag : 1; /**< The foreground color modification flag of the cell.*/
+    color bacground_color : 3;                /**< The background color of the cell.*/
+    enum background_flag background_flag : 1; /**< The background color modification flag of the cell.*/
   };
 
   static_assert(sizeof(attribute) == 1, "The VGA text mode attribute must fit inside a single byte.");
@@ -63,12 +63,21 @@ namespace teachos::arch::video::vga::text
    */
   namespace common_attributes
   {
+    /**
+     * @brief Make the affected cell display with a gray foreground and black background.
+     */
     [[maybe_unused]] auto constexpr gray_on_black =
         attribute{color::gray, foreground_flag::none, color::black, background_flag::none};
 
+    /**
+     * @brief Make the affected cell display with a green foreground and black background.
+     */
     [[maybe_unused]] auto constexpr green_on_black =
         attribute{color::green, foreground_flag::none, color::black, background_flag::none};
 
+    /**
+     * @brief Make the affected cell display with a white (gray + intense) foreground and red background.
+     */
     [[maybe_unused]] auto constexpr white_on_red =
         attribute{color::gray, foreground_flag::intense, color::red, background_flag::none};
   }  // namespace common_attributes
-- 
cgit v1.2.3