docs: begin breathe documentation

20 files changed, 227 insertions, 52 deletions

diff --git a/docs/conf.py b/docs/conf.py
index b8cfe69..99613b6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,7 +13,7 @@ author = "Felix Morgner"
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-#extensions = ["breathe"]
+extensions = ["breathe"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["pre/**"]
@@ -21,8 +21,9 @@ exclude_patterns = ["pre/**"]
 # -- Options Breathe ---------------------------------------------------------
 # https://breathe.readthedocs.io/en/stable/directives.html#config-values
 
-#breathe_projects = {"kernel": "../build/doxygen/xml"}
-#breathe_default_project = "kernel"
+breathe_projects = {"kernel": "../build/doxygen/xml"}
+breathe_default_project = "kernel"
+breathe_default_members = ('members', 'undoc-members', 'private-members')
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
diff --git a/docs/index.rst b/docs/index.rst
index 649e6de..425da57 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,10 +6,10 @@ Welcome to TeachOS Kernel's documentation!
    :caption: Contents:
 
    briefs
+   kapi
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
diff --git a/docs/kapi.rst b/docs/kapi.rst
new file mode 100644
index 0000000..4c60ab3
--- /dev/null
+++ b/docs/kapi.rst
@@ -0,0 +1,10 @@
+Kernel API
+==========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   kapi/*
+
diff --git a/docs/kapi/cio.rst b/docs/kapi/cio.rst
new file mode 100644
index 0000000..62a3639
--- /dev/null
+++ b/docs/kapi/cio.rst
@@ -0,0 +1,17 @@
+Character I/O Interface
+=======================
+
+.. doxygengroup:: kapi-cio
+    :content-only:
+
+Kernel-defined API
+------------------
+
+.. doxygengroup:: kapi-cio-kernel-defined
+    :content-only:
+
+Platform-defined API
+--------------------
+
+.. doxygengroup:: kapi-cio-platform-defined
+    :content-only:
diff --git a/docs/kapi/cpu.rst b/docs/kapi/cpu.rst
new file mode 100644
index 0000000..0793dd8
--- /dev/null
+++ b/docs/kapi/cpu.rst
@@ -0,0 +1,17 @@
+CPU Interface
+=============
+
+.. doxygengroup:: kapi-cpu
+    :content-only:
+
+Kernel-defined API
+------------------
+
+.. doxygengroup:: kapi-cpu-kernel-defined
+    :content-only:
+
+Platform-defined API
+--------------------
+
+.. doxygengroup:: kapi-cpu-platform-defined
+    :content-only:
diff --git a/docs/kapi/devices.rst b/docs/kapi/devices.rst
new file mode 100644
index 0000000..c9853a1
--- /dev/null
+++ b/docs/kapi/devices.rst
@@ -0,0 +1,17 @@
+Device Interface
+================
+
+.. doxygengroup:: kapi-devices
+    :content-only:
+
+Kernel-defined API
+------------------
+
+.. doxygengroup:: kapi-devices-kernel-defined
+    :content-only:
+
+Platform-defined API
+--------------------
+
+.. doxygengroup:: kapi-devices-platform-defined
+    :content-only:
diff --git a/docs/kapi/interrupts.rst b/docs/kapi/interrupts.rst
new file mode 100644
index 0000000..7150f07
--- /dev/null
+++ b/docs/kapi/interrupts.rst
@@ -0,0 +1,17 @@
+Interrupt Interface
+===================
+
+.. doxygengroup:: kapi-interrupts
+    :content-only:
+
+Kernel-defined API
+------------------
+
+.. doxygengroup:: kapi-interrupts-kernel-defined
+    :content-only:
+
+Platform-defined API
+--------------------
+
+.. doxygengroup:: kapi-interrupts-platform-defined
+    :content-only:
diff --git a/docs/kapi/memory.rst b/docs/kapi/memory.rst
new file mode 100644
index 0000000..9ee1584
--- /dev/null
+++ b/docs/kapi/memory.rst
@@ -0,0 +1,14 @@
+Memory Interface
+================
+
+Kernel-defined API
+------------------
+
+.. doxygengroup:: kapi-memory-kernel-defined
+    :content-only:
+
+Platform-defined API
+--------------------
+
+.. doxygengroup:: kapi-memory-platform-defined
+    :content-only:
diff --git a/docs/kapi/system.rst b/docs/kapi/system.rst
new file mode 100644
index 0000000..2eaea6d
--- /dev/null
+++ b/docs/kapi/system.rst
@@ -0,0 +1,14 @@
+System Interface
+================
+
+Kernel-defined API
+------------------
+
+.. doxygengroup:: kapi-system-kernel-defined
+    :content-only:
+
+Platform-defined API
+--------------------
+
+.. doxygengroup:: kapi-system-platform-defined
+    :content-only:
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 733e873..fc08790 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,3 @@
-Sphinx~=8.2.0
-sphinx_book_theme~=1.1.0
+Sphinx~=9.1.0
+sphinx_book_theme~=1.2.0
+breathe~=4.36.0
\ No newline at end of file
diff --git a/kapi/include/kapi/cio.hpp b/kapi/include/kapi/cio.hpp
index 71b5b02..8941a9f 100644
--- a/kapi/include/kapi/cio.hpp
+++ b/kapi/include/kapi/cio.hpp
@@ -11,27 +11,38 @@
 namespace kapi::cio
 {
 
-  //! @qualifier platform-defined
-  //! Initialize the character I/O subsystem.
-  //!
-  //! @note If a platform support character output, it shall ensure that when this function returns, basic character
-  //! output can be performed on the system.
-  auto init() -> void;
+  //! @addtogroup kapi-cio
+  //! @{
+  //! @}
+
+  //! @addtogroup kapi-cio-kernel-defined
+  //! @{
 
-  //! @qualifier kernel-defined
   //! Set the currently active output device.
   //!
   //! @param device A new output device.
   //! @return The previously active output device.
   auto set_output_device(output_device & device) -> std::optional<output_device *>;
 
-  //! @qualifier kernel-defined
   //! Write a string to the given output stream.
   //!
   //! @param stream The output stream to write to.
   //! @param text The text to write to the stream.
   auto write(output_stream stream, std::string_view text) -> void;
 
+  //! @}
+
+  //! @addtogroup kapi-cio-platform-defined
+  //! @{
+
+  //! Initialize the character I/O subsystem.
+  //!
+  //! If a platform support character output, it shall ensure that when this function returns, basic character
+  //! output can be performed on the system.
+  auto init() -> void;
+
+  //! @}
+
 }  // namespace kapi::cio
 
 #endif
diff --git a/kapi/include/kapi/cpu.hpp b/kapi/include/kapi/cpu.hpp
index c6aa6ff..d90365a 100644
--- a/kapi/include/kapi/cpu.hpp
+++ b/kapi/include/kapi/cpu.hpp
@@ -10,6 +10,9 @@
 namespace kapi::cpu
 {
 
+  //! @addtogroup kapi-cpu
+  //! @{
+
   //! An exception originating from the CPU directly.
   //!
   //! Exception generally model interrupts that are synchronous to the instruction stream. This means that they do not
@@ -58,25 +61,34 @@ namespace kapi::cpu
     bool is_user_mode{};
   };
 
-  //! @qualifier platform-defined
+  //! @}
+
+  //! @addtogroup kapi-cpu-kernel-defined
+  //! @{
+
+  //! Dispatch an exception to the appropriate handler.
+  //!
+  //! @param context The exception context.
+  //! @return Whether the exception was handled.
+  [[nodiscard]] auto dispatch(exception const & context) -> bool;
+
+  //! @}
+
+  //! @addtogroup kapi-cpu-platform-defined
+  //! @{
+
   //! Halt the CPU.
   //!
   //! This function terminates execution of the kernel.
   [[noreturn]] auto halt() -> void;
 
-  //! @qualifier platform-defined
   //! Perform early CPU initialization.
   //!
   //! When this function returns, the CPU is in a state where interrupt could be enabled. This function must not enable
   //! interrupts itself.
   auto init() -> void;
 
-  //! @qualifier kernel-defined
-  //! Dispatch an exception to the appropriate handler.
-  //!
-  //! @param context The exception context.
-  //! @return Whether the exception was handled.
-  [[nodiscard]] auto dispatch(exception const & context) -> bool;
+  //! @}
 
 }  // namespace kapi::cpu
 
diff --git a/kapi/include/kapi/devices.hpp b/kapi/include/kapi/devices.hpp
index 5c01b2f..c26efb9 100644
--- a/kapi/include/kapi/devices.hpp
+++ b/kapi/include/kapi/devices.hpp
@@ -8,7 +8,7 @@
 namespace kapi::devices
 {
 
-  //! @addtogroup kernel-defined
+  //! @addtogroup kapi-devices-kernel-defined
   //! @{
 
   //! Initialize the kernel's device management subsystem.
@@ -23,7 +23,7 @@ namespace kapi::devices
 
   //! @}
 
-  //! @addtogroup platform-defined
+  //! @addtogroup kapi-devices-platform-defined
   //! @{
 
   //! Initialize the platform's device tree.
diff --git a/kapi/include/kapi/devices/bus.hpp b/kapi/include/kapi/devices/bus.hpp
index ee774b7..052c062 100644
--- a/kapi/include/kapi/devices/bus.hpp
+++ b/kapi/include/kapi/devices/bus.hpp
@@ -17,6 +17,10 @@
 
 namespace kapi::devices
 {
+
+  //! @addtogroup kapi-devices
+  //! @{
+
   //! A bus device that represents a logical/physical tree of devices and busses.
   struct bus : device
   {
@@ -90,6 +94,9 @@ namespace kapi::devices
     kstd::vector<kstd::observer_ptr<device>> m_observers;
     std::atomic_flag m_initialized{};
   };
+
+  //! @}
+
 }  // namespace kapi::devices
 
 #endif
\ No newline at end of file
diff --git a/kapi/include/kapi/devices/device.hpp b/kapi/include/kapi/devices/device.hpp
index a049cf5..b7b6bba 100644
--- a/kapi/include/kapi/devices/device.hpp
+++ b/kapi/include/kapi/devices/device.hpp
@@ -7,6 +7,10 @@
 
 namespace kapi::devices
 {
+
+  //! @addtogroup kapi-devices
+  //! @{
+
   /**
    * @brief Base device identified by a major, minor number and name.
    */
@@ -76,6 +80,9 @@ namespace kapi::devices
     size_t m_minor;
     kstd::string m_name;
   };
+
+  //! @}
+
 }  // namespace kapi::devices
 
 #endif
\ No newline at end of file
diff --git a/kapi/include/kapi/devices/manager.hpp b/kapi/include/kapi/devices/manager.hpp
index 7817fbc..f19366e 100644
--- a/kapi/include/kapi/devices/manager.hpp
+++ b/kapi/include/kapi/devices/manager.hpp
@@ -13,7 +13,7 @@
 namespace kapi::devices
 {
 
-  //! @addtogroup kernel-defined
+  //! @addtogroup kapi-devices-kernel-defined
   //! @{
 
   //! Ask the kernel to allocate a new major number.
diff --git a/kapi/include/kapi/interrupts.hpp b/kapi/include/kapi/interrupts.hpp
index f72ef8c..4ba0684 100644
--- a/kapi/include/kapi/interrupts.hpp
+++ b/kapi/include/kapi/interrupts.hpp
@@ -6,9 +6,15 @@
 namespace kapi::interrupts
 {
 
+  //! @addtogroup kapi-interrupts
+  //! @{
+
+  //! A status that indicates whether an interrupt was handled by a handler.
   enum class status : bool
   {
+    //! The interrupt was not handled by any handler.
     unhandled,
+    //! The interrupt was handled by at least one handler.
     handled,
   };
 
@@ -27,35 +33,42 @@ namespace kapi::interrupts
     virtual auto handle_interrupt(std::uint32_t irq_number) -> status = 0;
   };
 
-  //! @qualifier platform-defined
-  //! Enable external interrupts.
-  auto enable() -> void;
+  //! @}
 
-  //! @qualifier platform-defined
-  //! Disable external interrupts.
-  auto disable() -> void;
+  //! @addtogroup kapi-interrupts-kernel-defined
+  //! @{
 
-  //! @qualifier kernel-defined
   //! Register an interrupt handler for the given IRQ number.
   //!
   //! @param irq_number The IRQ number to register the handler for.
   //! @param handler The interrupt handler to register.
   auto register_handler(std::uint32_t irq_number, handler & handler) -> void;
 
-  //! @qualifier kernel-defined
   //! Unregister a previously registered interrupt handler.
   //!
   //! @param irq_number The IRQ number to unregister the handler for.
   //! @param handler The interrupt handler to unregister.
   auto unregister_handler(std::uint32_t irq_number, handler & handler) -> void;
 
-  //! @qualifier kernel-defined
   //! Dispatch an interrupt to all registered handlers.
   //!
   //! @param irq_number The IRQ number to dispatch.
   //! @return status::handled if the interrupt was handled by at least one handler, status::unhandled otherwise.
   auto dispatch(std::uint32_t irq_number) -> status;
 
+  //! @}
+
+  //! @addtogroup kapi-interrupts-platform-defined
+  //! @{
+
+  //! Enable external interrupts.
+  auto enable() -> void;
+
+  //! Disable external interrupts.
+  auto disable() -> void;
+
+  //! @}
+
 }  // namespace kapi::interrupts
 
 #endif
\ No newline at end of file
diff --git a/kapi/include/kapi/memory.hpp b/kapi/include/kapi/memory.hpp
index e31fa34..914ca61 100644
--- a/kapi/include/kapi/memory.hpp
+++ b/kapi/include/kapi/memory.hpp
@@ -16,16 +16,9 @@
 namespace kapi::memory
 {
 
-  //! @qualifier platform-defined
-  //! Initialize the memory subsystem.
-  //!
-  //! @note This function must be implemented by the target platform.
-  //!
-  //! This function initializes the memory subsystem and activates the platform-specific frame allocator and page
-  //! mapper. When this function returns, a valid frame allocator and page mapper are expected to have been registered.
-  auto init() -> void;
+  //! @addtogroup kapi-memory-kernel-defined
+  //! @{
 
-  //! @qualifier kernel-defined
   //! Initialize the physical memory manager.
   //!
   //! This function initializes the kernel-wide physical memory manager. The function will invoke the handoff handler to
@@ -39,25 +32,21 @@ namespace kapi::memory
   //! allocator to hand off to is passed to the handler.
   auto init_pmm(std::size_t frame_count, void (&handoff_handler)(frame_allocator &)) -> void;
 
-  //! @qualifier kernel-defined
   //! Get the currently active frame allocator.
   auto get_frame_allocator() -> frame_allocator &;
 
-  //! @qualifier kernel-defined
   //! Set the currently active frame allocator.
   //!
   //! @param allocator A new frame allocator.
   //! @return The previously active frame allocator.
   auto set_frame_allocator(frame_allocator & allocator) -> std::optional<frame_allocator *>;
 
-  //! @qualifier kernel-defined
   //! Set the currently active page mapper.
   //!
   //! @param mapper A new page mapper.
   //! @return The previously active page mapper.
   auto set_page_mapper(page_mapper & mapper) -> std::optional<page_mapper *>;
 
-  //! @qualifier kernel-defined
   //! Allocate a new frame of physical memory
   //!
   //! @warning This function will panic if no frame allocator has been registered.
@@ -65,7 +54,6 @@ namespace kapi::memory
   //! @return An engaged std::optional iff. a frame could be allocated, std::nullopt otherwise.
   auto allocate_frame() -> std::optional<frame>;
 
-  //! @qualifier kernel-defined
   //! Allocate multiple new frames of physical memory
   //!
   //! @warning This function will panic if no frame allocator has been registered.
@@ -73,7 +61,6 @@ namespace kapi::memory
   //! @return An engaged std::optional iff. @p count frames could be allocated, std::nullopt otherwise.
   auto allocate_many_frames(std::size_t count) -> std::optional<std::pair<frame, std::size_t>>;
 
-  //! @qualifier kernel-defined
   //! Map a page onto a frame.
   //!
   //! @warning This function will panic if no page mapper has been registered, or the page has already been mapped.
@@ -85,7 +72,6 @@ namespace kapi::memory
   //! @return A pointer to the first byte of the mapped page.
   auto map(page page, frame frame, page_mapper::flags flags = page_mapper::flags::empty) -> std::byte *;
 
-  //! @qualifier kernel-defined
   //! Unmap a page.
   //!
   //! @warning This function will panic if no page mapper has been registered, or the page is not mapped.
@@ -93,6 +79,21 @@ namespace kapi::memory
   //! @param page The page to unmap
   auto unmap(page page) -> void;
 
+  //! @}
+
+  //! @addtogroup kapi-memory-platform-defined
+  //! @{
+
+  //! Initialize the memory subsystem.
+  //!
+  //! @note This function must be implemented by the target platform.
+  //!
+  //! This function initializes the memory subsystem and activates the platform-specific frame allocator and page
+  //! mapper. When this function returns, a valid frame allocator and page mapper are expected to have been registered.
+  auto init() -> void;
+
+  //! @}
+
 }  // namespace kapi::memory
 
 #endif
diff --git a/kapi/include/kapi/system.hpp b/kapi/include/kapi/system.hpp
index e5c43c5..8a20af9 100644
--- a/kapi/include/kapi/system.hpp
+++ b/kapi/include/kapi/system.hpp
@@ -7,7 +7,9 @@
 namespace kapi::system
 {
 
-  //! @qualifier kernel-defined
+  //! @addtogroup kapi-system-kernel-defined
+  //! @{
+
   //! Terminate kernel execution with the given error message.
   //!
   //! This function terminates the execution of the kernel and attempts to issue the given error message to the user.
@@ -15,10 +17,16 @@ namespace kapi::system
   //! @param message The message associated with the panic
   [[noreturn]] auto panic(std::string_view message, std::source_location = std::source_location::current()) -> void;
 
-  //! @qualifier platform-defined
+  //! @} // end group kernel-defined
+
+  //! @addtogroup kapi-system-platform-defined
+  //! @{
+
   //! A hook that runs once the memory subsystem has been initialized.
   auto memory_initialized() -> void;
 
+  //! @} // end group platform-defined
+
 }  // namespace kapi::system
 
 #endif
diff --git a/kapi/kapi.dox b/kapi/kapi.dox
new file mode 100644
index 0000000..929fc1f
--- /dev/null
+++ b/kapi/kapi.dox
@@ -0,0 +1,8 @@
+//! @namespace kapi
+//! The Kernel/Platform API
+//!
+//! This namespace defines the interface between the platform independent kernel and each supported platform.
+
+//! @defgroup kapi-kernel-defined Kernel-defined API
+
+//! @defgroup kapi-platform-defined Platform-defined API