chore: normalize kapi doc comments

19 files changed, 104 insertions, 8 deletions

diff --git a/kapi/kapi/boot.hpp b/kapi/kapi/boot.hpp
index 55ca9418..9fa3f786 100644
--- a/kapi/kapi/boot.hpp
+++ b/kapi/kapi/boot.hpp
@@ -3,15 +3,18 @@
 
 namespace kapi::boot
 {
-  //! @qualifier platform-defined
+  //! @addtogroup kapi-boot-platform-defined
+  //! @{
+
   //! Information passed from the early pre-main stage to the kernel executable.
   //!
   //! The specific structure of this type is defined on a platform level.
   struct information;
 
-  //! @qualifier platform-defined
   //! An object passed from the early pre-main stage to the kernel executable.
   extern "C" information const bootstrap_information;
+
+  //! @}
 }  // namespace kapi::boot
 
 #endif
diff --git a/kapi/kapi/capabilities/facet_id.hpp b/kapi/kapi/capabilities/facet_id.hpp
index 0ceae747..820814be 100644
--- a/kapi/kapi/capabilities/facet_id.hpp
+++ b/kapi/kapi/capabilities/facet_id.hpp
@@ -8,6 +8,9 @@
 namespace kapi::capabilities
 {
 
+  //! @addtogroup kapi-capabilities
+  //! @{
+
   //! A tag to mark the presence of a given behavioral or data facet.
   struct facet_id
   {
@@ -31,6 +34,8 @@ namespace kapi::capabilities
     std::string_view m_name;
   };
 
+  //! @}
+
 }  // namespace kapi::capabilities
 
 #endif
diff --git a/kapi/kapi/cio/output_device.hpp b/kapi/kapi/cio/output_device.hpp
index 9fe25577..c241a10c 100644
--- a/kapi/kapi/cio/output_device.hpp
+++ b/kapi/kapi/cio/output_device.hpp
@@ -8,6 +8,9 @@
 namespace kapi::cio
 {
 
+  //! @addtogroup kapi-cio
+  //! @{
+
   enum struct output_stream
   {
     stdout,
@@ -34,6 +37,8 @@ namespace kapi::cio
     output_device() = default;
   };
 
+  //! @}
+
 }  // namespace kapi::cio
 
 #endif
diff --git a/kapi/kapi/devices/bus_protocol.hpp b/kapi/kapi/devices/bus_protocol.hpp
index 5d63a388..5a47ecef 100644
--- a/kapi/kapi/devices/bus_protocol.hpp
+++ b/kapi/kapi/devices/bus_protocol.hpp
@@ -16,6 +16,9 @@ namespace kapi::devices
 
   struct bus;
 
+  //! @addtogroup kapi-devices
+  //! @{
+
   //! Bus specific behavior.
   //!
   //! A bus protocol defines how a bus discovers its attached children, and how drivers are matched against devices. It
@@ -43,6 +46,8 @@ namespace kapi::devices
         -> kstd::result<std::uint32_t> = 0;
   };
 
+  //! @}
+
 }  // namespace kapi::devices
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/devices/error.hpp b/kapi/kapi/devices/error.hpp
index cf33daa9..4ef419d4 100644
--- a/kapi/kapi/devices/error.hpp
+++ b/kapi/kapi/devices/error.hpp
@@ -10,6 +10,9 @@
 namespace kapi::devices
 {
 
+  //! @addtogroup kapi-devices
+  //! @{
+
   enum struct driver_match_errc
   {
     //! The driver did not match on the given device.
@@ -20,6 +23,11 @@ namespace kapi::devices
     invalid_device_signature = 3,
   };
 
+  //! @}
+
+  //! @addtogroup kapi-devices-kernel-defined
+  //! @{
+
   [[nodiscard]] auto driver_match_category() noexcept -> kstd::error_category const &;
 
   [[nodiscard]] constexpr auto inline make_error_code(driver_match_errc error) noexcept -> kstd::error_code
@@ -27,6 +35,8 @@ namespace kapi::devices
     return kstd::error_code{static_cast<int>(error), driver_match_category()};
   }
 
+  //! @}
+
 }  // namespace kapi::devices
 
 namespace kstd
diff --git a/kapi/kapi/devices/resource.hpp b/kapi/kapi/devices/resource.hpp
index 1284ce10..40be703e 100644
--- a/kapi/kapi/devices/resource.hpp
+++ b/kapi/kapi/devices/resource.hpp
@@ -15,6 +15,9 @@
 namespace kapi::devices
 {
 
+  //! @addtogroup kapi-devices
+  //! @{
+
   //! The type of a resource.
   enum struct resource_type
   {
@@ -28,6 +31,8 @@ namespace kapi::devices
     dma,
   };
 
+  //! @}
+
 }  // namespace kapi::devices
 
 template<>
@@ -68,6 +73,9 @@ struct kstd::formatter<kapi::devices::resource_type>
 namespace kapi::devices
 {
 
+  //! @addtogroup kapi-devices
+  //! @{
+
   //! A range of the memory-mapped I/O address space.
   struct mmio_range
   {
@@ -225,6 +233,8 @@ namespace kapi::devices
     } m_value;
   };
 
+  //! @}
+
 }  // namespace kapi::devices
 
 #endif
diff --git a/kapi/kapi/filesystem/block_special_file.hpp b/kapi/kapi/filesystem/block_special_file.hpp
index 6060c5ea..daf4a97b 100644
--- a/kapi/kapi/filesystem/block_special_file.hpp
+++ b/kapi/kapi/filesystem/block_special_file.hpp
@@ -14,6 +14,9 @@
 namespace kapi::filesystem
 {
 
+  //! @addtogroup kapi-filesystem
+  //! @{
+
   struct block_special_file
   {
     constexpr auto static id = kapi::capabilities::facet_id{"block"};
@@ -53,6 +56,8 @@ namespace kapi::filesystem
     [[nodiscard]] auto virtual capacity() const -> kstd::bytes = 0;
   };
 
+  //! @}
+
 }  // namespace kapi::filesystem
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/filesystem/character_special_file.hpp b/kapi/kapi/filesystem/character_special_file.hpp
index c63d535b..5524f97f 100644
--- a/kapi/kapi/filesystem/character_special_file.hpp
+++ b/kapi/kapi/filesystem/character_special_file.hpp
@@ -14,6 +14,9 @@
 namespace kapi::filesystem
 {
 
+  //! @addtogroup kapi-filesystem
+  //! @{
+
   struct character_special_file
   {
     constexpr auto static id = kapi::capabilities::facet_id{"char"};
@@ -34,6 +37,8 @@ namespace kapi::filesystem
     auto virtual write(std::span<std::byte const> buffer) -> kstd::result<kstd::bytes> = 0;
   };
 
+  //! @}
+
 }  // namespace kapi::filesystem
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/filesystem/device_number.hpp b/kapi/kapi/filesystem/device_number.hpp
index 55c813f5..cdfd116b 100644
--- a/kapi/kapi/filesystem/device_number.hpp
+++ b/kapi/kapi/filesystem/device_number.hpp
@@ -9,6 +9,9 @@
 namespace kapi::filesystem
 {
 
+  //! @addtogroup kapi-filesystem
+  //! @{
+
   //! A POSIX device number.
   struct device_number
   {
@@ -20,6 +23,8 @@ namespace kapi::filesystem
     constexpr auto friend operator<=>(device_number, device_number) noexcept -> std::strong_ordering = default;
   };
 
+  //! @}
+
 }  // namespace kapi::filesystem
 
 #endif
diff --git a/kapi/kapi/filesystem/file_status.hpp b/kapi/kapi/filesystem/file_status.hpp
index bb3c776a..25ea16f6 100644
--- a/kapi/kapi/filesystem/file_status.hpp
+++ b/kapi/kapi/filesystem/file_status.hpp
@@ -12,6 +12,9 @@
 namespace kapi::filesystem
 {
 
+  //! @addtogroup kapi-filesystem
+  //! @{
+
   struct file_status
   {
     std::uint32_t mode{};
@@ -21,6 +24,8 @@ namespace kapi::filesystem
     std::uint32_t link_count{};
   };
 
+  //! @}
+
 }  // namespace kapi::filesystem
 
 #endif
diff --git a/kapi/kapi/filesystem/file_type.hpp b/kapi/kapi/filesystem/file_type.hpp
index cb346b71..b44016c5 100644
--- a/kapi/kapi/filesystem/file_type.hpp
+++ b/kapi/kapi/filesystem/file_type.hpp
@@ -8,6 +8,9 @@
 namespace kapi::filesystem
 {
 
+  //! @addtogroup kapi-filesystem
+  //! @{
+
   enum struct file_type : std::uint32_t
   {
     fifo = 0x1000,
@@ -41,6 +44,8 @@ namespace kapi::filesystem
     return static_cast<file_type>(mode & file_type_mask) == file_type::regular;
   }
 
+  //! @}
+
 }  // namespace kapi::filesystem
 
 #endif
diff --git a/kapi/kapi/filesystem/seek.hpp b/kapi/kapi/filesystem/seek.hpp
index 42bee22d..0b9caa50 100644
--- a/kapi/kapi/filesystem/seek.hpp
+++ b/kapi/kapi/filesystem/seek.hpp
@@ -6,6 +6,9 @@
 namespace kapi::filesystem
 {
 
+  //! @addtogroup kapi-filesystem
+  //! @{
+
   //! The origin for a seek operation.
   enum struct seek_origin
   {
@@ -17,6 +20,8 @@ namespace kapi::filesystem
     end,
   };
 
+  //! @}
+
 }  // namespace kapi::filesystem
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/memory/address.hpp b/kapi/kapi/memory/address.hpp
index 8ed6d37a..a7f5ac92 100644
--- a/kapi/kapi/memory/address.hpp
+++ b/kapi/kapi/memory/address.hpp
@@ -15,7 +15,9 @@
 namespace kapi::memory
 {
 
-  //! @qualifier kernel-defined
+  //! @addtogroup kapi-memory
+  //! @{
+
   //! A tag for different address types.
   enum struct address_type : bool
   {
@@ -23,7 +25,6 @@ namespace kapi::memory
     physical,
   };
 
-  //! @qualifier kernel-defined
   //! A physical or virtual address.
   //!
   //! This convenience wrapper type is used to ensure that no linear address is passed where a physical one is expected
@@ -219,6 +220,8 @@ namespace kapi::memory
   //! A physical address.
   using physical_address = address<address_type::physical>;
 
+  //! @}
+
 }  // namespace kapi::memory
 
 namespace kstd
diff --git a/kapi/kapi/memory/chunk.hpp b/kapi/kapi/memory/chunk.hpp
index 45e2ccfd..987c41f4 100644
--- a/kapi/kapi/memory/chunk.hpp
+++ b/kapi/kapi/memory/chunk.hpp
@@ -11,7 +11,9 @@
 namespace kapi::memory
 {
 
-  //! @qualifier kernel-defined
+  //! @addtogroup kapi-memory
+  //! @{
+
   //! A fixed-size unit of memory, indexed by a number.
   //!
   //! @tparam ChunkType The CRTP type of the deriving class
@@ -104,6 +106,8 @@ namespace kapi::memory
     std::size_t m_number{};
   };
 
+  //! @}
+
 }  // namespace kapi::memory
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/memory/frame.hpp b/kapi/kapi/memory/frame.hpp
index e423fa4f..aafca5c7 100644
--- a/kapi/kapi/memory/frame.hpp
+++ b/kapi/kapi/memory/frame.hpp
@@ -11,8 +11,9 @@
 
 namespace kapi::memory
 {
+  //! @addtogroup kapi-memory
+  //! @{
 
-  //! @qualifier kernel-defined
   //! A handle to a frame of physical memory.
   //!
   //! @note Contrary to the address types, this type is modeled using inheritance to support future extensions.
@@ -43,6 +44,8 @@ namespace kapi::memory
     {}
   };
 
+  //! @}
+
 }  // namespace kapi::memory
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/memory/frame_allocator.hpp b/kapi/kapi/memory/frame_allocator.hpp
index 784ea932..783bd3cb 100644
--- a/kapi/kapi/memory/frame_allocator.hpp
+++ b/kapi/kapi/memory/frame_allocator.hpp
@@ -12,6 +12,9 @@
 namespace kapi::memory
 {
 
+  //! @addtogroup kapi-memory
+  //! @{
+
   //! The interface of all frame allocators.
   //!
   //! A frame allocator is responsible for the allocation, and deallocation, of frames of physical memory. Frames
@@ -61,6 +64,8 @@ namespace kapi::memory
     frame_allocator() = default;
   };
 
+  //! @}
+
 }  // namespace kapi::memory
 
 #endif  // TEACHOS_KAPI_MEMORY_FRAME_ALLOCATOR_HPP
\ No newline at end of file
diff --git a/kapi/kapi/memory/layout.hpp b/kapi/kapi/memory/layout.hpp
index bcb27fbc..3dc5882e 100644
--- a/kapi/kapi/memory/layout.hpp
+++ b/kapi/kapi/memory/layout.hpp
@@ -10,6 +10,9 @@
 namespace kapi::memory
 {
 
+  //! @addtogroup kapi-memory
+  //! @{
+
   //! The size of a single page of virtual memory.
   //!
   //! Platforms that use different sizes of pages are expected to emulate 4 KiB pages towards the kernel.
@@ -49,6 +52,8 @@ namespace kapi::memory
     return physical_address{address.raw() - higher_half_direct_map_base.raw()};
   }
 
+  //! @}
+
 }  // namespace kapi::memory
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/memory/page.hpp b/kapi/kapi/memory/page.hpp
index d9875346..2a609833 100644
--- a/kapi/kapi/memory/page.hpp
+++ b/kapi/kapi/memory/page.hpp
@@ -12,7 +12,9 @@
 namespace kapi::memory
 {
 
-  //! @qualifier kernel-defined
+  //! @addtogroup kapi-memory
+  //! @{
+
   //! A handle to a page of virtual memory.
   //!
   //! @note Contrary to the address types, this type is modeled using inheritance to support future extensions.
@@ -33,6 +35,8 @@ namespace kapi::memory
     {}
   };
 
+  //! @}
+
 }  // namespace kapi::memory
 
 #endif
\ No newline at end of file
diff --git a/kapi/kapi/memory/page_mapper.hpp b/kapi/kapi/memory/page_mapper.hpp
index ec7e7c68..3deb4702 100644
--- a/kapi/kapi/memory/page_mapper.hpp
+++ b/kapi/kapi/memory/page_mapper.hpp
@@ -15,7 +15,9 @@
 namespace kapi::memory
 {
 
-  //! @qualifier platform-implemented
+  //! @addtogroup kapi-memory
+  //! @{
+
   //! The interface of a type allowing the mapping, and unmapping, of pages onto frames.
   struct page_mapper
   {
@@ -77,6 +79,8 @@ namespace kapi::memory
     page_mapper() = default;
   };
 
+  //! @}
+
 }  // namespace kapi::memory
 
 namespace kstd