chore: normalize kernel doc comments

18 files changed, 283 insertions, 485 deletions

diff --git a/kernel/kernel/devices/block_device_utils.hpp b/kernel/kernel/devices/block_device_utils.hpp
index 03fee8cc..b9c8c416 100644
--- a/kernel/kernel/devices/block_device_utils.hpp
+++ b/kernel/kernel/devices/block_device_utils.hpp
@@ -10,18 +10,10 @@
 #include <cstddef>
 #include <span>
 
-/**
-@brief Utility functions for block devices, such as reading/writing data at specific offsets. These functions handle
-the necessary logic to interact with block devices, such as calculating block boundaries and ensuring proper access
-patterns. They abstract away the details of block device interactions, providing a simple interface for reading and
-writing data to block devices.
-*/
 namespace kernel::devices::block_device_utils
 {
 
-  /**
-   * @brief Information describing the transfer window for one block index.
-   */
+  //! Information describing the transfer window for one block index.
   struct transfer_info
   {
     kstd::bytes offset;
diff --git a/kernel/kernel/filesystem/devfs/filesystem.hpp b/kernel/kernel/filesystem/devfs/filesystem.hpp
index 3a4e7ec6..50a87de9 100644
--- a/kernel/kernel/filesystem/devfs/filesystem.hpp
+++ b/kernel/kernel/filesystem/devfs/filesystem.hpp
@@ -31,10 +31,8 @@ namespace kernel::filesystem::devfs
                       kstd::enable_shared_from_this<filesystem>,
                       device_number_registry_observer
   {
-    //! @copydoc kernel::filesystem::filesystem::mount
     auto mount(kstd::shared_ptr<kernel::filesystem::inode> const & backing_inode) -> kstd::result<void> override;
 
-    //! @copydoc kernel::filesystem::filesystem::lookup
     [[nodiscard]] auto lookup(kstd::shared_ptr<kernel::filesystem::inode> const & parent, std::string_view name) const
         -> kstd::result<kstd::shared_ptr<kernel::filesystem::inode>> override;
 
diff --git a/kernel/kernel/filesystem/devfs/inode.hpp b/kernel/kernel/filesystem/devfs/inode.hpp
index d2f5291e..e907c02e 100644
--- a/kernel/kernel/filesystem/devfs/inode.hpp
+++ b/kernel/kernel/filesystem/devfs/inode.hpp
@@ -11,33 +11,16 @@
 
 namespace kernel::filesystem::devfs
 {
-  /**
-  @brief Inode implementation for the devfs filesystem.
-  This inode represents root device node in the /dev directory.
-  */
+  //! Inode implementation for the devfs filesystem.
+  //!
+  //! This inode represents root device node in the /dev directory.
   struct inode : kernel::filesystem::inode
   {
-    /**
-    @brief Reads from the devfs directory inode.
-    @param buffer Destination buffer.
-    @param offset Read offset in bytes.
-    @return Number of bytes read (always 0 because this inode does not expose file data).
-    */
     [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const
         -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Writes to the devfs directory inode.
-    @param buffer Source buffer.
-    @param offset Write offset in bytes.
-    @return Number of bytes written (always 0 because writes are not supported for this inode).
-    */
     auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Check if this inode represents a directory.
-    @return returns true, since this inode represents the /dev directory in the devfs filesystem.
-    */
     [[nodiscard]] auto is_directory() const -> bool override;
   };
 }  // namespace kernel::filesystem::devfs
diff --git a/kernel/kernel/filesystem/device_inode.hpp b/kernel/kernel/filesystem/device_inode.hpp
index 5c26266e..49b17d89 100644
--- a/kernel/kernel/filesystem/device_inode.hpp
+++ b/kernel/kernel/filesystem/device_inode.hpp
@@ -60,16 +60,8 @@ namespace kernel::filesystem
     //! @name Property Queries
     //! @{
 
-    /**
-    @brief Check if this inode represents a block device.
-    @return true iff. the underlying device is a block device, false otherwise.
-    */
     [[nodiscard]] auto is_block_device() const -> bool override;
 
-    /**
-    @brief Check if this inode represents a character device.
-    @return true iff. the underlying device is a character device, false otherwise.
-    */
     [[nodiscard]] auto is_character_device() const -> bool override;
 
     //! @}
@@ -86,10 +78,9 @@ namespace kernel::filesystem
     //! @name Device Access
     //! @{
 
-    /**
-    @brief Get the associated device.
-    @return A reference to the associated device.
-    */
+    //! @brief Get the device, if any, associated with this inode.
+    //!
+    //! @return The associated device, of nullptr if no such device exists.
     [[nodiscard]] auto device() const -> kstd::shared_ptr<kapi::devices::device> const &;
 
     //! @}
diff --git a/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp b/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp
index f7a7ce9e..16f6d6e2 100644
--- a/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp
+++ b/kernel/kernel/filesystem/ext2/block_group_descriptor.hpp
@@ -6,9 +6,7 @@
 
 namespace kernel::filesystem::ext2
 {
-  /**
-  @brief Represents a block group descriptor in the ext2 filesystem.
-  */
+  //! A block group descriptor in the ext2 filesystem.
   struct [[gnu::packed]] block_group_descriptor
   {
     uint32_t block_bitmap;
diff --git a/kernel/kernel/filesystem/ext2/filesystem.hpp b/kernel/kernel/filesystem/ext2/filesystem.hpp
index c61eadd1..6a066f25 100644
--- a/kernel/kernel/filesystem/ext2/filesystem.hpp
+++ b/kernel/kernel/filesystem/ext2/filesystem.hpp
@@ -24,9 +24,7 @@
 
 namespace kernel::filesystem::ext2
 {
-  /**
-  @brief Constants related to the ext2 filesystem.
-  */
+  //! Constants related to the ext2 filesystem.
   namespace constants
   {
     constexpr kstd::bytes inline base_block_size = kstd::bytes{1024};
@@ -51,118 +49,85 @@ namespace kernel::filesystem::ext2
     constexpr uint16_t inline mode_character_device = 0x2000;
   }  // namespace constants
 
-  /**
-  @brief A filesystem implementation for the ext2 filesystem format. This class provides methods for mounting an ext2
-  filesystem, and looking up inodes.
-  */
+  //! The Second Extended Filesystem (ext2)
   struct filesystem final : kernel::filesystem::filesystem
   {
-    /**
-    @brief Initializes the ext2 filesystem with the given @p backing_inode.
-    @param backing_inode The backing inode to mount.
-    @return The result of the mount operation.
-    */
     auto mount(kstd::shared_ptr<kernel::filesystem::inode> const & backing_inode) -> kstd::result<void> override;
 
-    /**
-    @brief Looks up an inode by @p name within a @p parent directory.
-    @param parent The parent directory inode.
-    @param name The name of the inode to look up.
-    @return A pointer to the found inode, or a null pointer if not found.
-    */
     [[nodiscard]] auto lookup(kstd::shared_ptr<kernel::filesystem::inode> const & parent, std::string_view name) const
         -> kstd::result<kstd::shared_ptr<kernel::filesystem::inode>> override;
 
-    /**
-    @brief Creates a new inode with @p name within a @p parent directory.
-    @param parent The parent directory inode.
-    @param name The name of the inode to create.
-    @param inode_type The type of inode to be created.
-    @param raw_device The number of the device represented by the new inode, if any.
-    @return A pointer to the created inode, or a null pointer if creation failed.
-    */
     [[nodiscard]] auto create_inode(kstd::shared_ptr<kernel::filesystem::inode> const & parent, std::string_view name,
                                     vfs_types::inode_type inode_type,
                                     std::optional<kapi::filesystem::device_number> raw_device = std::nullopt)
         -> kstd::result<kstd::shared_ptr<kernel::filesystem::inode>> override;
 
-    /**
-    @brief Gets the size of a block in the filesystem.
-    @return The size of a block in bytes.
-    */
+    //! Get the size of a block in the filesystem.
+    //!
+    //! @return The size of a block in bytes.
     [[nodiscard]] auto block_size() const -> kstd::bytes;
 
-    /**
-    @brief Gets the revision level of the filesystem.
-    @return The revision level.
-    */
+    //! Get the revision level of the filesystem.
+    //!
+    //! @return The revision level.
     [[nodiscard]] auto revision_level() const -> uint32_t;
 
-    /**
-    @brief Reads a block from the backing device into the provided buffer.
-    @param block_number The number of the block to read.
-    @param buffer The buffer to read the block data into.
-    @return The number of bytes read.
-    */
+    //! Read a block from the backing inode into the provided buffer.
+    //!
+    //! @param block_number The number of the block to read.
+    //! @param buffer The buffer to read the block data into.
+    //! @return The number of bytes read.
     auto read_block(uint32_t block_number, void * buffer) const -> kstd::result<kstd::bytes>;
 
-    /**
-    @brief Writes a block of data from the provided buffer to the backing device.
-    @param block_number The number of the block to write.
-    @param buffer The buffer containing the data to write.
-    @return The number of bytes written.
-    */
+    //! Write a block of data from the provided buffer to the backing inode.
+    //!
+    //! @param block_number The number of the block to write.
+    //! @param buffer The buffer containing the data to write.
+    //! @return The number of bytes written.
     auto write_block(uint32_t block_number, void const * buffer) -> kstd::result<kstd::bytes>;
 
-    /**
-    @brief Allocates a specified number of blocks.
-    @param count The number of blocks to allocate.
-    @return An optional vector of the allocated block numbers, or a nullopt if allocation fails.
-    */
+    //! Allocate a specified number of blocks.
+    //!
+    //! @param count The number of blocks to allocate.
+    //! @return A vector of the allocated block numbers.
     auto allocate_blocks(size_t count) -> kstd::result<kstd::vector<uint32_t>>;
 
-    /**
-    @brief Gets the size of an inode in the filesystem.
-    @return The size of an inode in bytes.
-    */
+    //! Get the size of an inode in the filesystem.
+    //!
+    //! @return The size of an inode in bytes.
     [[nodiscard]] auto inode_size() const -> kstd::bytes;
 
-    /**
-    @brief Gets the number of blocks allocated to an inode.
-    @param data The inode data.
-    @return The number of blocks allocated to the inode.
-    */
+    //! Get the number of blocks allocated to an inode.
+    //!
+    //! @param data The inode data.
+    //! @return The number of blocks allocated to the inode.
     [[nodiscard]] auto inode_block_count(inode_data const & data) const -> uint32_t;
 
-    /**
-    @brief Updates the number of blocks allocated to an inode.
-    @param data The inode data.
-    @param delta The change in the number of blocks.
-    */
+    //! Update the number of blocks allocated to an inode.
+    //!
+    //! @param data The inode data.
+    //! @param delta The change in the number of blocks.
     auto update_inode_block_count(inode_data & data, uint32_t delta) -> void;
 
-    /**
-    @brief Writes an inode to the backing device.
-    @param inode_number The number of the inode to write.
-    @param data The inode data to write.
-    */
+    //! Write an inode to the backing inode.
+    //!
+    //! @param inode_number The number of the inode to write.
+    //! @param data The inode data to write.
     auto write_inode(uint32_t inode_number, inode_data const & data) -> kstd::result<void>;
 
-    /**
-    @brief Maps an inode block index to a global block number.
-    @param inode_block_index The index of the block within the inode.
-    @param data The inode data.
-    @return The global block number on success, an error otherwise.
-    */
+    //! Map an inode block index to a global block number.
+    //!
+    //! @param inode_block_index The index of the block within the inode.
+    //! @param data The inode data.
+    //! @return The global block number on success, an error otherwise.
     [[nodiscard]] auto map_inode_block_index_to_global_block_number(size_t inode_block_index, inode_data data) const
         -> kstd::result<std::size_t>;
 
-    /**
-    @brief Writes a global block number to an inode block index.
-    @param block_index The index of the block within the inode.
-    @param data The inode data.
-    @param global_block_number The global block number to write.
-    */
+    //! Write a global block number to an inode block index.
+    //!
+    //! @param block_index The index of the block within the inode.
+    //! @param data The inode data.
+    //! @param global_block_number The global block number to write.
     auto write_global_block_number_to_inode_block_index(size_t block_index, inode_data & data,
                                                         uint32_t global_block_number) -> kstd::result<void>;
 
diff --git a/kernel/kernel/filesystem/ext2/inode.hpp b/kernel/kernel/filesystem/ext2/inode.hpp
index 51508c0d..61961f6c 100644
--- a/kernel/kernel/filesystem/ext2/inode.hpp
+++ b/kernel/kernel/filesystem/ext2/inode.hpp
@@ -19,9 +19,7 @@ namespace kernel::filesystem::ext2
 {
   struct filesystem;
 
-  /**
-  @brief Represents the data associated with an ext2 inode.
-  */
+  //! The data for a single ext2 inode.
   struct [[gnu::packed]] inode_data
   {
     uint16_t mode;
@@ -46,66 +44,38 @@ namespace kernel::filesystem::ext2
 
   struct inode : kernel::filesystem::inode
   {
-    /**
-    @brief Create an ext2 inode associated with the given filesystem.
-    @param fs The ext2 filesystem that this inode belongs to.
-    @param inode_number The inode number on disk.
-    @param data The data associated with this inode, read from the disk.
-    */
+    //! Create an ext2 inode associated with the given filesystem.
+    //!
+    //! @param fs The ext2 filesystem that this inode belongs to.
+    //! @param inode_number The inode number on disk.
+    //! @param data The data associated with this inode, read from the disk.
     explicit inode(filesystem * fs, uint32_t inode_number, inode_data const & data);
 
-    /**
-    @brief Reads from the ext2 inode into a @p buffer, starting at the specified @p offset and for a given @p size.
-    @param buffer Destination buffer.
-    @param offset Read offset in bytes.
-    @return Number of bytes read.
-    */
     [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const
         -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Writes to the ext2 inode into a @p buffer, starting at the specified @p offset and for a given @p size.
-    @param buffer Source buffer.
-    @param offset Write offset in bytes.
-    @return Number of bytes written.
-    */
     auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Appends the specified number of blocks to the inode.
-    @param count The number of blocks to append.
-    @return true if the blocks were successfully appended, false otherwise.
-    */
+    //! Append the specified number of blocks to this inode.
+    //!
+    //! @param count The number of blocks to append.
+    //! @return true if the blocks were successfully appended, false otherwise.
     auto append_blocks(size_t count) -> bool;
 
-    /**
-    @brief Get the data associated with this inode.
-    @return A const reference to the inode data.
-     */
+    //! Get the data associated with this inode.
+    //!
+    //! @return A const reference to the inode data.
     [[nodiscard]] auto data() const -> inode_data const &;
 
-    /**
-    @brief Get the data associated with this inode.
-    @return A reference to the inode data.
-     */
+    //! Get the data associated with this inode.
+    //!
+    //! @return A reference to the inode data.
     [[nodiscard]] auto data_mutable() -> inode_data &;
 
-    /**
-    @brief Check if this inode represents a directory.
-    @return returns true if this inode represents a directory, false otherwise.
-     */
     [[nodiscard]] auto is_directory() const -> bool override;
 
-    /**
-    @brief Check if this inode represents a regular file.
-    @return returns true if this inode represents a regular file, false otherwise.
-     */
     [[nodiscard]] auto is_regular() const -> bool override;
 
-    /**
-    @brief Check if this inode represents a symbolic link.
-    @return returns true if this inode represents a symbolic link, false otherwise.
-     */
     [[nodiscard]] auto is_symbolic_link() const -> bool override;
 
     [[nodiscard]] auto is_block_device() const -> bool override;
@@ -116,27 +86,27 @@ namespace kernel::filesystem::ext2
 
     [[nodiscard]] auto raw_device() const -> std::optional<kapi::filesystem::device_number> override;
 
-    /**
-    @brief Get the size of the file represented by this inode.
-    @return The size of the file in bytes.
-     */
+    //! Get the size of the file represented by this inode.
+    //!
+    //! @return The size of the file in bytes.
     [[nodiscard]] auto size() const -> kstd::bytes;
 
-    /**
-    @brief Set the size of the file represented by this inode.
-    @param new_size The new size of the file in bytes.
-     */
+    //! Set the size of the file represented by this inode.
+    //!
+    //! @param new_size The new size of the file in bytes.
     auto set_size(kstd::bytes new_size) -> void;
 
-    /**
-    @brief Get the inode number of this inode.
-    @return The inode number.
-    */
+    //! @brief Get the inode number of this inode.
+    //!
+    //! @return The inode number.
     [[nodiscard]] auto number() const -> uint32_t;
 
   private:
+    //! The filesystem this inode belongs to.
     filesystem * m_filesystem;
+    //! The inode number on disk.
     uint32_t m_inode_number{};
+    //! The inode data.
     inode_data m_data{};
   };
 }  // namespace kernel::filesystem::ext2
diff --git a/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp b/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp
index 2dfa507d..9c9d162d 100644
--- a/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp
+++ b/kernel/kernel/filesystem/ext2/linked_directory_entry.hpp
@@ -6,9 +6,7 @@
 
 namespace kernel::filesystem::ext2
 {
-  /**
-  @brief Represents a linked directory entry in the ext2 filesystem.
-  */
+  //! A linked directory entry in the ext2 filesystem.
   struct [[gnu::packed]] linked_directory_entry
   {
     uint32_t inode;
diff --git a/kernel/kernel/filesystem/ext2/superblock.hpp b/kernel/kernel/filesystem/ext2/superblock.hpp
index 73fd4b5e..0fe5d4e5 100644
--- a/kernel/kernel/filesystem/ext2/superblock.hpp
+++ b/kernel/kernel/filesystem/ext2/superblock.hpp
@@ -6,9 +6,7 @@
 
 namespace kernel::filesystem::ext2
 {
-  /**
-  @brief Represents the superblock in the ext2 filesystem.
-  */
+  //! The superblock in the ext2 filesystem.
   struct [[gnu::packed]] superblock
   {
     uint32_t inodes_count;
diff --git a/kernel/kernel/filesystem/filesystem.cpp b/kernel/kernel/filesystem/filesystem.cpp
index ac0d0ebc..5cd7f9d5 100644
--- a/kernel/kernel/filesystem/filesystem.cpp
+++ b/kernel/kernel/filesystem/filesystem.cpp
@@ -16,6 +16,7 @@ namespace kernel::filesystem
 {
   namespace
   {
+    // TODO: replace with filesystem type registry.
     constexpr auto static filesystem_factories = std::array{
       []() { return kstd::make_shared<ext2::filesystem>(); },
     };
@@ -29,6 +30,7 @@ namespace kernel::filesystem
       kapi::system::panic("[FILESYSTEM] cannot mount filesystem: backing inode is null.");
     }
 
+    // TODO: replace with filesystem type registry lookup.
     for (auto & factory : filesystem_factories)
     {
       auto fs = factory();
diff --git a/kernel/kernel/filesystem/filesystem.hpp b/kernel/kernel/filesystem/filesystem.hpp
index b5017c24..668fd06e 100644
--- a/kernel/kernel/filesystem/filesystem.hpp
+++ b/kernel/kernel/filesystem/filesystem.hpp
@@ -16,68 +16,64 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief A base class for implementing filesystems in the kernel. This class provides a common interface for managing
-  files and directories within the virtual filesystem.
-  */
+  //! The base class for all filesystems.
+  //!
+  //! This class provides a common interface for managing files and directories within the virtual filesystem.
+  //! Filesystem implementations must derive from this class.
   struct filesystem
   {
-    /**
-    @brief Virtual destructor for the filesystem.
-    */
+    //! Virtual destructor enabling polymorphic destruction.
     virtual ~filesystem() = default;
 
-    /**
-    @brief Probes the given @p backing_inode to determine if it contains a recognizable filesystem, and if so, mounts it
-    and returns a pointer to the mounted filesystem instance. This method iterates through known filesystem types and
-    attempts to initialize it with the backing inode until the mount was successful or all types have been tried.
-    @param backing_inode The inode to probe and mount.
-    @return A pointer to the mounted filesystem instance if successful, an error otherwise.
-    @warning Panics if @p backing_inode is null.
-    */
+    //! Probes the given inode to determine if it contains a recognizable filesystem, and if so, mount it.
+    //!
+    //! @warning This function panics if @p backing_inode is null.
+    //!
+    //! @param backing_inode The inode to probe and mount.
+    //! @return A pointer to the mounted filesystem instance on success, an error otherwise.
     auto static probe_and_mount(kstd::shared_ptr<inode> const & backing_inode)
         -> kstd::result<kstd::shared_ptr<filesystem>>;
 
-    /**
-    @brief Initializes the filesystem with the given @p backing_inode.
-    @param backing_inode The inode to use as the backing inode for the filesystem. (This is typically the inode
-    representing the block device or another inode which contains the filesystem data.)
-    @return Nothing on success, and error otherwise.
-    */
+    //! Initializes the filesystem with the given inode.
+    //!
+    //! Typically, the backing inode is the inode representing the block device or another inode which contains the
+    //! filesystem data (e.g. a file on an already mounted filesystem).
+    //!
+    //! @param backing_inode The inode to use as the backing inode for the filesystem.
+    //! @return Nothing on success, and error otherwise.
     virtual auto mount(kstd::shared_ptr<inode> const & backing_inode) -> kstd::result<void>;
 
-    /**
-    @brief Looks up a child inode within the given @p parent inode with the specified @p name. This method must be
-    implemented by concrete filesystem subclasses to provide the logic for traversing the filesystem structure and
-    finding the requested inode.
-    @param parent The parent inode.
-    @param name The name of the child inode to look up.
-    @return A pointer to the requested child inode, an error otherwise.
-    */
+    //! Find a child inode below the given parent inode with the specified name.
+    //!
+    //! This method must be implemented by concrete filesystem subclasses to provide the logic for traversing the
+    //! filesystem structure and finding the requested inode.
+    //!
+    //! @param parent The parent inode.
+    //! @param name The name of the child inode to look up.
+    //! @return A pointer to the requested child inode on success, an error otherwise.
     [[nodiscard]] virtual auto lookup(kstd::shared_ptr<inode> const & parent, std::string_view name) const
         -> kstd::result<kstd::shared_ptr<inode>> = 0;
 
-    /**
-    @brief Creates a new inode with @p name within a @p parent directory.
-    @param parent The parent directory inode.
-    @param name The name of the inode to create.
-    @param inode_type The type of inode to be created.
-    @param raw_device The device number the new inode should represent.
-    @return A pointer to the created inode, or a null pointer if creation failed.
-    */
+    //! Create a new inode with the given name below a given parent inode.
+    //!
+    //! @param parent The parent inode.
+    //! @param name The name of the inode to create.
+    //! @param inode_type The type of inode to be created.
+    //! @param raw_device The device number the new inode should represent, if any.
+    //! @return A pointer to the created inode on success, an error otherwise.
     [[nodiscard]] virtual auto create_inode(kstd::shared_ptr<inode> const & parent, std::string_view name,
                                             vfs_types::inode_type inode_type,
                                             std::optional<kapi::filesystem::device_number> raw_device = std::nullopt)
         -> kstd::result<kstd::shared_ptr<inode>> = 0;
 
-    /**
-    @brief Returns a reference to the root inode of the filesystem.
-    */
+    //! Get the root inode of the file system.
+    //!
+    //! @return A reference to the root inode.
     [[nodiscard]] auto root_inode() const -> kstd::shared_ptr<inode> const &;
 
-    /**
-    @brief Returns a reference to the backing inode of the filesystem.
-    */
+    //! Get the backing inode of the file system.
+    //!
+    //! @return A reference to the backing inode.
     [[nodiscard]] auto backing_inode() const -> kstd::shared_ptr<inode> const &;
 
   protected:
diff --git a/kernel/kernel/filesystem/mount.hpp b/kernel/kernel/filesystem/mount.hpp
index aff43c78..b906def5 100644
--- a/kernel/kernel/filesystem/mount.hpp
+++ b/kernel/kernel/filesystem/mount.hpp
@@ -12,76 +12,54 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief Represents a mounted filesystem in the kernel.
-  */
+  //! A mounted filesystem
   struct mount
   {
-    /**
-    @brief Creates a mount for the given @p filesystem at the specified @p mount_path. The @p mount_dentry represents
-    the dentry where the filesystem is mounted, and the @p root_dentry represents the root dentry of the mounted
-    filesystem.
-    @param mount_dentry The dentry where the filesystem is mounted.
-    @param root_dentry The root dentry of the mounted filesystem.
-    @param fs The filesystem instance being mounted.
-    @param parent_mount The mount that contains the mount_dentry.
-    @param source_mount The mount that the filesystem originates from.
-    */
+    //! Create a new mount with the given parameters.
+    //!
+    //! @param mount_dentry The directory entry where the filesystem is mounted.
+    //! @param root_dentry The root directory entry of the mounted filesystem.
+    //! @param fs The filesystem instance being mounted.
+    //! @param parent_mount The parent mount which contains the mount_dentry.
+    //! @param source_mount The mount that the filesystem originates from.
     mount(kstd::shared_ptr<dentry> const & mount_dentry, kstd::shared_ptr<dentry> const & root_dentry,
           kstd::shared_ptr<filesystem> const & fs, kstd::shared_ptr<mount> const & parent_mount,
           kstd::shared_ptr<mount> const & source_mount);
 
-    /**
-    @brief Get the dentry where the filesystem is mounted.
-    */
+    //! Get the directory entry where the filesystem is mounted.
     [[nodiscard]] auto mount_dentry() const -> kstd::shared_ptr<dentry> const &;
 
-    /**
-    @brief Get the root dentry of the mounted filesystem.
-    */
+    //! Get the root directory entry of the mounted filesystem.
     [[nodiscard]] auto root_dentry() const -> kstd::shared_ptr<dentry> const &;
 
-    /**
-    @brief Get the filesystem instance being mounted.
-    */
+    //! Get the filesystem instance being mounted.
     [[nodiscard]] auto get_filesystem() const -> kstd::shared_ptr<filesystem> const &;
 
-    /**
-    @brief Get the path at which the filesystem is mounted.
-    */
+    //! Get the path at which the filesystem is mounted.
     [[nodiscard]] auto mount_path() const -> kstd::string;
 
-    /**
-    @brief Get the parent mount that this mount was attached beneath.
-    */
+    //! Get the parent mount that this mount was attached beneath.
     [[nodiscard]] auto parent_mount() const -> kstd::shared_ptr<mount> const &;
 
-    /**
-    @brief Get the source mount where this mount originates from.
-    */
+    //! Get the source mount where this mount originates from.
     [[nodiscard]] auto source_mount() const -> kstd::shared_ptr<mount>;
 
-    /**
-    @brief Increment the reference count for this mount.
-    */
+    //! Increment the reference count for this mount.
     auto increment_ref_count() -> void;
 
-    /**
-    @brief Decrement the reference count for this mount.
-    @warning Throws if ref_count is zero.
-    */
+    //! Decrement the reference count for this mount.
+    //!
+    //! @warning This function panics if the reference count is already zero.
     auto decrement_ref_count() -> void;
 
-    /**
-    @brief Check if the mount is ready to be unmounted.
-    @return True if the mount is ready to be unmounted, false otherwise.
-    */
+    //! Check if the mount is ready to be unmounted.
+    //!
+    //! @return True if the mount is ready to be unmounted, false otherwise.
     [[nodiscard]] auto is_ready_to_unmount() const -> bool;
 
-    /**
-    @brief Get the current reference count for this mount.
-    @return The current reference count.
-    */
+    //! Get the current reference count for this mount.
+    //!
+    //! @return The current reference count.
     [[nodiscard]] auto ref_count() const -> size_t;
 
   private:
diff --git a/kernel/kernel/filesystem/mount_table.hpp b/kernel/kernel/filesystem/mount_table.hpp
index f1c2050d..678a5927 100644
--- a/kernel/kernel/filesystem/mount_table.hpp
+++ b/kernel/kernel/filesystem/mount_table.hpp
@@ -10,14 +10,10 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief A table for managing mounted filesystems in the kernel.
-  */
+  //! A table managing all mounted filesystems.
   struct mount_table
   {
-    /**
-    @brief Results for mount table operations.
-    */
+    //! Results for mount table operations.
     enum class operation_result : int
     {
       removed = 0,
@@ -26,24 +22,22 @@ namespace kernel::filesystem
       cannot_be_unmounted = -3
     };
 
-    /**
-    @brief Adds a mount to the table.
-    @param mount The mount to add.
-    */
+    //! Add a mount to the table.
+    //!
+    //! @param mount The mount to add.
     auto add_mount(kstd::shared_ptr<mount> const & mount) -> void;
 
-    /**
-    @brief Removes the topmost mount at the given @p path.
-    @param path The mount path to remove.
-    @return The result of the removal operation.
-    */
-    [[nodiscard]] auto remove_mount(std::string_view path) -> operation_result;
-
-    /**
-    @brief Finds the mount with the exact mount path matching the given @p path.
-    @param path The path to match against the mount paths in the table.
-    @return A pointer to the mount with the exact matching path, or a null pointer if no mount matches the path.
-    */
+    //! Remove the topmost mount at the given @p path.
+    //!
+    //! @param path The mount path to remove.
+    //! @return The result of the removal operation.
+    [[nodiscard]] auto remove_mount(std::string_view path)
+        -> operation_result;  // TODO: replace return type with kstd::result
+
+    //! Find the mount with the exact mount path matching the given path.
+    //!
+    //! @param path The path to match against the mount paths in the table.
+    //! @return A pointer to the mount with the exact matching path on success, nullpointer otherwise.
     [[nodiscard]] auto find_mount(std::string_view path) const -> kstd::shared_ptr<mount>;
 
   private:
diff --git a/kernel/kernel/filesystem/open_file_descriptor.hpp b/kernel/kernel/filesystem/open_file_descriptor.hpp
index a39dbab8..735ea7a2 100644
--- a/kernel/kernel/filesystem/open_file_descriptor.hpp
+++ b/kernel/kernel/filesystem/open_file_descriptor.hpp
@@ -14,39 +14,27 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief Represents an open file descriptor in the filesystem. This class encapsulates the state of an open file,
-  including a reference to the associated dentry and the current file offset.
-  */
+  //! An open file.
+  //!
+  //! This class encapsulates the state of an open file, including a reference to the associated directory and the
+  //! current byte offset within the file.
   struct open_file_descriptor
   {
-    /**
-    @brief Constructs an open file descriptor for the given @p dentry.
-    @param dentry The dentry to associate with the open file descriptor.
-    */
+    //! Create an new open file descriptor for a given directory entry.
+    //!
+    //! @param dentry The directory entry to associate with the open file descriptor.
     explicit open_file_descriptor(kstd::shared_ptr<dentry> const & dentry);
 
-    /**
-    @brief Destructor for the open file descriptor.
-    */
-    ~open_file_descriptor() = default;
-
-    /**
-    @brief Reads data from the open file descriptor into a @p buffer, starting at the current file offset and for a
-    given
-    @p size. The file offset is advanced by the number of bytes read.
-    @param buffer The buffer to read data into.
-    @return The number of bytes read.
-    */
+    //! Read data from the open file descriptor into a buffer.
+    //!
+    //! @param buffer The buffer to read data into.
+    //! @return The number of bytes read on success, an error otherwise.
     auto read(std::span<std::byte> buffer) -> kstd::result<kstd::bytes>;
 
-    /**
-    @brief Writes data to the open file descriptor from a @p buffer, starting at the current file offset and for a
-    given
-    @p size. The file offset is advanced by the number of bytes written.
-    @param buffer The buffer to write data from.
-    @return The number of bytes written.
-    */
+    //! Write data to the open file descriptor from a buffer.
+    //!
+    //! @param buffer The buffer to write data from.
+    //! @return The number of bytes written on success, an error otherwise.
     auto write(std::span<std::byte const> buffer) -> kstd::result<kstd::bytes>;
 
     //! Move the read/write offset of the file.
@@ -56,16 +44,14 @@ namespace kernel::filesystem
     //! @return the new offset on success, an error otherwise.
     auto seek(kstd::offset offset, kapi::filesystem::seek_origin origin) -> kstd::result<kstd::bytes>;
 
-    /**
-    @brief Returns the current file offset for this open file descriptor.
-    @return The current file offset in bytes.
-     */
+    //! Get the current file offset for this open file descriptor.
+    //!
+    //! @return The current file offset in bytes.
     [[nodiscard]] auto offset() const -> kstd::bytes;
 
-    /**
-    @brief Return a reference to the dentry associated with this open file descriptor.
-    @return A reference to the associated dentry.
-     */
+    //! Get a reference to the directory entry associated with this open file descriptor.
+    //!
+    //! @return A reference to the associated directory entry.
     [[nodiscard]] auto get_dentry() const -> kstd::shared_ptr<dentry> const &;
 
   private:
diff --git a/kernel/kernel/filesystem/open_file_table.hpp b/kernel/kernel/filesystem/open_file_table.hpp
index fe42c2bb..ddc1ea16 100644
--- a/kernel/kernel/filesystem/open_file_table.hpp
+++ b/kernel/kernel/filesystem/open_file_table.hpp
@@ -12,49 +12,39 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief A table for managing file descriptors in the filesystem. This class provides methods for adding, retrieving,
-  and removing open file descriptors.
-  */
+  //! @brief A table for managing file descriptors in the filesystem.
+  //!
+  //! This class provides methods for adding, retrieving, and removing open file descriptors.
   struct open_file_table
   {
-    /**
-    @brief Initialize the global open file table. This method creates the singleton instance of the open file table.
-    @warning Panics if called more than once.
-    */
+    //! Initialize the global open file table.
+    //!
+    //! @warning This function panics if called more than once.
     auto static init() -> void;
 
-    /**
-    @brief Get the global open file table instance.
-    @return A reference to the global open file table.
-    @warning Panics if the open file table has not been initialized.
-    */
+    //! Get the global open file table instance.
+    //!
+    //! @warning Panics if the open file table has not been initialized.
+    //!
+    //! @return A reference to the global open file table.
     auto static get() -> open_file_table &;
 
-    /**
-    @brief Destructor for the open file table.
-    */
-    ~open_file_table() = default;
-
-    /**
-    @brief Add a file to the open file table.
-    @param fd The file descriptor to add.
-    @return The file descriptor index assigned to the file, or -1 on failure.
-    */
+    //! Add a file to the open file table.
+    //!
+    //! @param fd The file descriptor to add.
+    //! @return The file descriptor index assigned to the file on success, an error otherwise.
     auto add_file(kstd::shared_ptr<open_file_descriptor> const & fd) -> kstd::result<std::size_t>;
 
-    /**
-    @brief Get a file from the open file table.
-    @param fd The file descriptor index to retrieve.
-    @return A pointer to the requested file descriptor, or a null pointer if not found.
-    */
+    //! Get a file from the open file table.
+    //!
+    //! @param fd The file descriptor index to retrieve.
+    //! @return The requested file descriptor on success, an error otherwise.
     [[nodiscard]] auto file(size_t fd) const -> kstd::result<kstd::shared_ptr<open_file_descriptor>>;
 
-    /**
-    @brief Remove a file from the open file table.
-    @param fd The file descriptor index to remove.
-    @return 0 on success, or -1 on failure.
-    */
+    //! Remove a file from the open file table.
+    //!
+    //! @param fd The file descriptor index to remove.
+    //! @return Nothin on success, an error otherwise.
     auto remove_file(size_t fd) -> kstd::result<void>;
 
   private:
diff --git a/kernel/kernel/filesystem/path.hpp b/kernel/kernel/filesystem/path.hpp
index a9d4cbd9..4dc0dbce 100644
--- a/kernel/kernel/filesystem/path.hpp
+++ b/kernel/kernel/filesystem/path.hpp
@@ -11,55 +11,47 @@
 
 namespace kernel::filesystem::path
 {
-  /**
-  @brief Provides utilities for handling filesystem paths, including validation and splitting into components.
-  */
 
-  /**
-  @brief Checks if the given path is within the maximum allowed length.
-  @param path The path to check.
-  @return true if the path length is valid, false otherwise.
-  */
+  //! Check if the given path is within the maximum allowed length.
+  //!
+  //! @param path The path to check.
+  //! @return @c true if the path length is valid, @c false otherwise.
   auto inline is_valid_path_length(std::string_view path) -> bool
   {
     return path.length() < kernel::filesystem::constants::max_path_length;
   }
 
-  /**
-  @brief Checks if the given path is a valid absolute path (starts with '/').
-  @param path The path to check.
-  @return true if the path is a valid absolute path, false otherwise.
-  */
+  //! Check if the given path is an absolute path.
+  //!
+  //! @param path The path to check.
+  //! @return @c true if the path is an absolute path, @c false otherwise.
   auto inline is_valid_absolute_path(std::string_view path) -> bool
   {
     return !path.empty() && path.front() == '/' && is_valid_path_length(path);
   }
 
-  /**
-  @brief Checks if the given path is a valid relative path (doesn't start with '/').
-  @param path The path to check.
-  @return true if the path is a valid relative path, false otherwise.
-  */
+  //! Check if the given path is a relative path.
+  //!
+  //! @param path The path to check.
+  //! @return @c true if the path is a relative path, @c false otherwise.
   auto inline is_valid_relative_path(std::string_view path) -> bool
   {
     return !path.empty() && path.front() != '/' && is_valid_path_length(path);
   }
 
-  /**
-  @brief Checks if the given path is a valid path (either absolute or relative).
-  @param path The path to check.
-  @return true if the path is a valid path, false otherwise.
-  */
+  //! Check if the given path is a valid path.
+  //!
+  //! @param path The path to check.
+  //! @return @c true if the path is a valid path, @c false otherwise.
   auto inline is_valid_path(std::string_view path) -> bool
   {
     return is_valid_absolute_path(path) || is_valid_relative_path(path);
   }
 
-  /**
-  @brief Splits the given path into its components.
-  @param path The path to split.
-  @return A range of strings representing the components of the path.
-  */
+  //! Split the given path into its components.
+  //!
+  //! @param path The path to split.
+  //! @return A range of strings representing the components of the path.
   auto inline split(std::string_view path)
   {
     return std::views::split(path, '/') | std::views::filter([](auto const & part) { return !part.empty(); }) |
@@ -67,11 +59,10 @@ namespace kernel::filesystem::path
                [](auto const & part) { return kstd::string(std::string_view(part.begin(), part.end())); });
   }
 
-  /**
-  @brief Splits the given path into its parent path and filename components.
-  @param path The path to split.
-  @return A pair of string views representing the parent path and filename.
-  */
+  //! Split the given path into its parent path and filename components.
+  //!
+  //! @param path The path to split.
+  //! @return A pair of string views representing the parent path and filename.
   auto inline split_into_path_and_filename(std::string_view path) -> std::pair<std::string_view, std::string_view>
   {
     if (path.empty())
diff --git a/kernel/kernel/filesystem/rootfs/inode.hpp b/kernel/kernel/filesystem/rootfs/inode.hpp
index e9e85d7d..2a1c3858 100644
--- a/kernel/kernel/filesystem/rootfs/inode.hpp
+++ b/kernel/kernel/filesystem/rootfs/inode.hpp
@@ -14,32 +14,14 @@
 
 namespace kernel::filesystem::rootfs
 {
-  /**
-  @brief Represents an inode in the rootfs filesystem.
-  */
+  //! An inode in the rootfs filesystem.
   struct inode : kernel::filesystem::inode
   {
-    /**
-    @brief Reads from the rootfs directory inode.
-    @param buffer Destination buffer.
-    @param offset Read offset in bytes.
-    @return Number of bytes read (always 0 because this inode does not expose file data).
-    */
     [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const
         -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Writes to the rootfs directory inode.
-    @param buffer Source buffer.
-    @param offset Write offset in bytes.
-    @return Number of bytes written (always 0 because writes are not supported for this inode).
-    */
     auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Check if this inode represents a directory.
-    @return returns true, since this inode represents the / directory in the rootfs filesystem.
-    */
     [[nodiscard]] auto is_directory() const -> bool override;
   };
 }  // namespace kernel::filesystem::rootfs
diff --git a/kernel/kernel/filesystem/vfs.hpp b/kernel/kernel/filesystem/vfs.hpp
index b2b7e3a8..f4f5b477 100644
--- a/kernel/kernel/filesystem/vfs.hpp
+++ b/kernel/kernel/filesystem/vfs.hpp
@@ -22,12 +22,13 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief The virtual filesystem (VFS) is responsible for managing mounted filesystems and providing a unified interface
-  for file operations across different filesystem types. The VFS maintains a mount table to keep track of mounted
-  filesystems and their associated mount points. It provides methods for opening files by path, which involves resolving
-  the path to the appropriate mounted filesystem and delegating the file operation to that filesystem's implementation.
-  */
+  //! The virtual filesystem interface.
+  //!
+  //! The virtual filesystem (VFS) is responsible for managing mounted filesystems and providing a unified interface
+  //! for file operations across different filesystem types. The VFS maintains a mount table to keep track of mounted
+  //! filesystems and their associated mount points. It provides methods for opening files by path, which involves
+  //! resolving the path to the appropriate mounted filesystem and delegating the file operation to that filesystem's
+  //! implementation.
   struct vfs
   {
     using dentry_ptr = kstd::shared_ptr<dentry>;
@@ -36,66 +37,54 @@ namespace kernel::filesystem
 
     vfs();
 
-    /**
-    @brief Initialize the virtual filesystem.
-    @warning Panics if the VFS has already been initialized.
-    */
+    //! Initialize the virtual filesystem.
+    //!
+    //! @warning This function panics if the VFS has already been initialized.
     auto static init() -> void;
 
-    /**
-    @brief Get the singleton instance of the virtual filesystem.
-    @return A reference to the VFS instance.
-    @warning Panics if the VFS has not been initialized yet.
-    */
+    //! Get the singleton instance of the virtual filesystem.
+    //!
+    //! @warning This function panics if the VFS has not been initialized yet.
+    //!
+    //! @return A reference to the VFS instance.
     auto static get() -> vfs &;
 
-    /**
-    @brief Destructor for the VFS.
-    */
-    ~vfs() = default;
-
-    /**
-    @brief Open a file by its @p path. This method resolves the path and returns the corresponding dentry.
-    @param path The path to the file to open.
-    @return A shared pointer to the dentry on success or an error code on failure.
-    */
+    //! Open a file by its path.
+    //!
+    //! @param path The path to the file to open.
+    //! @return A shared pointer to the dentry on success or an error code on failure.
     auto open(std::string_view path) -> kstd::result<dentry_ptr>;
 
-    /**
-    @brief Close a file by its associated @p path.
-    @param path The path to the file to close.
-    @return Nothing on success or an error code on failure.
-    */
+    //! Close a file by its associated path.
+    //!
+    //! @param path The path to the file to close.
+    //! @return Nothing on success or an error code on failure.
     auto close(std::string_view path) -> kstd::result<void>;
 
-    /**
-    @brief Mount a @p source path to a specific @p target path.
-    @param source The source of the filesystem to mount.
-    @param target The path where the filesystem should be mounted.
-    @return Nothing on success or an error code on failure.
-    */
+    //! Mount a source path to a specific target path.
+    //!
+    //! @param source The source of the filesystem to mount.
+    //! @param target The path where the filesystem should be mounted.
+    //! @return Nothing on success or an error code on failure.
     auto mount(std::string_view source, std::string_view target) -> kstd::result<void>;
 
-    /**
-    @brief Unmount the filesystem mounted at the specified @p path.
-    @param path The path where the filesystem is mounted.
-    @return Nothing on success or an error code on failure.
-    */
+    //! Unmount the filesystem mounted at the specified path.
+    //!
+    //! @param path The path where the filesystem is mounted.
+    //! @return Nothing on success or an error code on failure.
     auto unmount(std::string_view path) -> kstd::result<void>;
 
-    /**
-    @brief Create a new directory at the specified @p path.
-    @param path The path where the new directory should be created.
-    @return The result of the mkdir operation.
-    */
+    //! Create a new directory at the specified path.
+    //!
+    //! @param path The path where the new directory should be created.
+    //! @return Nothing on success, an error otherwise.
     auto mkdir(std::string_view path) -> kstd::result<void>;
 
-    /**
-    @brief Create a new file at the specified @p path.
-    @param path The path where the new file should be created.
-    @return The result of the create operation.
-    */
-    // TODO remove again after the open method supports an optional create flag
+    //! Create a new file at the specified path.
+    //!
+    //! @param path The path where the new file should be created.
+    //! @return Nothing on success, an error otherwise.
+    // TODO remove after the open method supports flags.
     auto create(std::string_view path) -> kstd::result<void>;
 
     //! Get the status of the file at a given path.
@@ -110,16 +99,13 @@ namespace kernel::filesystem
         -> kstd::result<void>;
 
   private:
-    /**
-     * Note: Resolving a dentry requires traversing mount points; since the
-     * associated 'mount' object is discovered as a byproduct of this
-     * traversal, we return it alongside the dentry to avoid redundant
-     * lookups in callers that require mount context.
-     *
-     * If only one component is needed, the convenience wrappers can be used:
-     * - resolve_path() for the dentry only.
-     * - find_mount() for the mount context only.
-     */
+    // Note: Resolving a dentry requires traversing mount points; since the associated 'mount' object is discovered as a
+    // byproduct of this traversal, we return it alongside the dentry to avoid redundant lookups in callers that require
+    // mount context.
+    //
+    // If only one component is needed, the convenience wrappers can be used:
+    // - resolve_path() for the dentry only.
+    // - find_mount() for the mount context only.
     [[nodiscard]] auto resolve_path_internal(std::string_view path) const
         -> kstd::result<std::pair<dentry_ptr, mount_ptr>>;