docs: clean up some of the documentation

11 files changed, 155 insertions, 112 deletions

diff --git a/kernel/kernel/devices/storage.tests.cpp b/kernel/kernel/devices/storage.tests.cpp
index 46dfb5ab..6eeeba67 100644
--- a/kernel/kernel/devices/storage.tests.cpp
+++ b/kernel/kernel/devices/storage.tests.cpp
@@ -20,7 +20,7 @@ TEST_CASE("Storage devices attached with init() are reachable from the root bus"
   auto module = kapi::boot_modules::module{
     .name = "test_module type=ramdisk",
     .start_address = kapi::memory::linear_address{storage.data()},
-    .size = storage.size(),
+    .size = kstd::bytes{storage.size()},
   };
   auto device = kstd::make_shared<kapi::boot_modules::device>(0, module);
 
diff --git a/kernel/kernel/filesystem/constants.hpp b/kernel/kernel/filesystem/constants.hpp
index 8388d058..cebbf530 100644
--- a/kernel/kernel/filesystem/constants.hpp
+++ b/kernel/kernel/filesystem/constants.hpp
@@ -5,9 +5,13 @@
 
 namespace kernel::filesystem::constants
 {
+  //! The maximum allowed length for any path in the system.
   constexpr size_t inline max_path_length = 4096;
 
+  //! The maximum allowed path length for the target of a symlink.
   constexpr size_t inline symlink_max_path_length = 4096;
+
+  //! The maximum number of loops allowed in a path, via symlinks.
   constexpr size_t inline symloop_max = 40;
 }  // namespace kernel::filesystem::constants
 
diff --git a/kernel/kernel/filesystem/dentry.hpp b/kernel/kernel/filesystem/dentry.hpp
index ea689485..30d8c4f9 100644
--- a/kernel/kernel/filesystem/dentry.hpp
+++ b/kernel/kernel/filesystem/dentry.hpp
@@ -12,84 +12,75 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief Represents a directory entry (dentry) in the filesystem. A dentry is a node in the directory tree that
-  represents a file or directory. It contains a reference to its parent dentry, a reference to the associated real
-  filesystem inode, and a list of child dentries.
-  */
+  //! A directory entry in the filesystem.
   struct dentry
   {
-    /**
-    @brief Flags for the dentry.
-    */
+    //! Flags for the dentry.
     enum class dentry_flags : uint32_t
     {
       is_mount_point = 1 << 0
     };
 
-    /**
-    @brief Create a dentry with the given @p parent, associated @p inode, and optional @p name. The dentry is
-    initialized with the provided parent and inode, and the name is stored for lookup purposes.
-    @param parent The parent dentry.
-    @param inode The associated inode for this dentry.
-    @param name The name of the dentry (optional).
-    */
+    //! Create a directory entry with the given parent, associated inode, and name.
+    //!
+    //! @warning This function will panic if invoked with a null pointer for the inode argument.
+    //!
+    //! @param parent The parent directory entry, if any.
+    //! @param inode The associated inode for this dentry.
+    //! @param name The name of the dentry.
     dentry(kstd::shared_ptr<dentry> const & parent, kstd::shared_ptr<inode> const & inode, std::string_view name);
 
-    /**
-    @brief Get the associated inode.
-    @return A reference to the associated inode.
-    */
+    //! Get this entrys associated inode.
+    //!
+    //! @return The inode associated with this directory entry.
     [[nodiscard]] auto get_inode() const -> kstd::shared_ptr<inode> const &;
 
-    /**
-    @brief Get the parent dentry.
-    @return A reference to the parent dentry.
-    */
+    //! Get this entrys parent directory entry.
+    //!
+    //! @return The parent directory entry, or @p nullptr if this entry has no parent.
     [[nodiscard]] auto parent() const -> kstd::shared_ptr<dentry>;
 
-    /**
-    @brief Get the name of the dentry.
-    @return The name of the dentry.
-    */
+    //! Get this entrys name.
+    //!
+    //! @return The name of this directory entry.
     [[nodiscard]] auto name() const -> std::string_view;
 
-    /**
-      @brief Get the full path of the dentry by traversing up to the root.
-      @return The full path of the dentry.
-     */
+    //! Get the full path of this entry by traversing up to the root.
+    //!
+    //! @note This function performs a full path traversal to the root. Even if all entries on that path a cached, this
+    //! may imply a non insignificant time penalty, as traversal complexity is linear in the depth of the path.
+    //!
+    //! @return The full path of this directory entry.
     [[nodiscard]] auto absolute_path() const -> kstd::string;
 
-    /**
-    @brief Add a @p child dentry.
-    @param child The child dentry to add.
-    */
+    //! Add a child to this entry.
+    //!
+    //! @param child The child directory entry to add.
     auto add_child(kstd::shared_ptr<dentry> const & child) -> void;
 
-    /**
-    @brief Find a child dentry by @p name.
-    @param name The name of the child dentry to find.
-    @return A pointer to the found child dentry, or a null pointer if not found.
-    */
+    //! Find a child entry with the given name.
+    //!
+    //! @note This function performs no path traversal. The name supplied to this function must name a direct child of
+    //! this directory entry in order for it to be found.
+    //!
+    //! @param name The name of the child directory entry to find.
+    //! @return A pointer to the child dentry if it exists, a null pointer otherwise.
     [[nodiscard]] auto find_child(std::string_view name) const -> kstd::shared_ptr<dentry>;
 
-    /**
-    @brief Set a @p flag for the dentry.
-    @param flag The flag to set.
-    */
+    //! Set a flag for this entry.
+    //!
+    //! @param flag The flag to set.
     auto set_flag(dentry_flags flag) -> void;
 
-    /**
-    @brief Unset a @p flag for the dentry.
-    @param flag The flag to unset.
-    */
+    //! Clear a flag from this entry.
+    //!
+    //! @param flag The flag to clear.
     auto unset_flag(dentry_flags flag) -> void;
 
-    /**
-    @brief Check if the dentry has a specific @p flag.
-    @param flag The flag to check.
-    @return True if the dentry has the flag, false otherwise.
-    */
+    //! Check if this entry has a specific flag set.
+    //!
+    //! @param flag The flag to check.
+    //! @return @c true iff. the flag is set on this entry, @c false otherwise.
     [[nodiscard]] auto has_flag(dentry_flags flag) const -> bool;
 
   private:
diff --git a/kernel/kernel/filesystem/devfs/inode.hpp b/kernel/kernel/filesystem/devfs/inode.hpp
index a68baef6..4dbd8bae 100644
--- a/kernel/kernel/filesystem/devfs/inode.hpp
+++ b/kernel/kernel/filesystem/devfs/inode.hpp
@@ -21,7 +21,6 @@ namespace kernel::filesystem::devfs
     @brief Reads from the devfs directory inode.
     @param buffer Destination buffer.
     @param offset Read offset in bytes.
-    @param size Number of bytes requested.
     @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
@@ -31,7 +30,6 @@ namespace kernel::filesystem::devfs
     @brief Writes to the devfs directory inode.
     @param buffer Source buffer.
     @param offset Write offset in bytes.
-    @param size Number of bytes requested.
     @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;
diff --git a/kernel/kernel/filesystem/device_inode.hpp b/kernel/kernel/filesystem/device_inode.hpp
index 663974ed..6e81a577 100644
--- a/kernel/kernel/filesystem/device_inode.hpp
+++ b/kernel/kernel/filesystem/device_inode.hpp
@@ -16,50 +16,49 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief Inode implementation for device inodes in the filesystem. This inode represents a device file that provides
-  access to a device registered in the system. The device inode allows reading from and writing to the associated
-  device.
-  */
-  struct device_inode : inode
+
+  //! Inode implementation for device inodes in the filesystem.
+  //!
+  //! An object of this type represents a device file that provides access to a device registered in the system. The
+  //! device inode allows reading from and writing to the associated device.
+  struct device_inode final : inode
   {
-    /**
-    @brief Create a device inode with the given @p device.
-    @param device The device to associate with the inode.
-    */
+    //! Create an inode representing a given device.
+    //!
+    //! @param device The device to associate with the inode.
     explicit device_inode(kstd::shared_ptr<kapi::devices::device> const & device);
 
     //! Create a device inode wrapping a device and carrying another inodes metadata.
     //!
-    //! This constructor enable reconstituting a persistend device node from a filesystem.
+    //! This constructor enables reconstituting a persistend device node from a filesystem. POSIX status information
+    //! will be queried by the origin inode.
+    //!
+    //! @param device The device that the new inode should represent.
+    //! @param origin The original inode being wrapped by the new inode.
     device_inode(kstd::shared_ptr<kapi::devices::device> const & device, kstd::shared_ptr<inode> const & origin);
 
-    /**
-    @brief Read data from the device inode (and in the background from the associated device) into a @p buffer, starting
-    at @p offset and reading @p size bytes.
-    @param buffer The buffer to read data into.
-    @param offset The offset to read from.
-    @param size The number of bytes to read.
-    @return The number of bytes read.
-    */
+    //! @name I/O Operations
+    //! @{
+
+    //! Read data, starting at a given offset, from the device into a buffer;
+    //!
+    //! @param buffer The buffer to read data into.
+    //! @param offset The offset to read from.
+    //! @return The number of bytes read on success, an error on otherwise.
     [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const
         -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Write data to the device inode (and in the background from the associated device) from a @p buffer, starting
-    at @p offset and writing @p size bytes.
-    @param buffer The buffer containing data to write.
-    @param offset The offset to write to.
-    @param size The number of bytes to write.
-    @return The number of bytes written.
-    */
+    //! Write data from a buffer to the device, at a given offset.
+    //!
+    //! @param buffer The buffer containing data to write.
+    //! @param offset The offset to write to.
+    //! @return The number of bytes written on success, an error otherwise.
     auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override;
 
-    /**
-    @brief Get the associated device.
-    @return A reference to the associated device.
-    */
-    [[nodiscard]] auto device() const -> kstd::shared_ptr<kapi::devices::device> const &;
+    //! @}
+
+    //! @name Property Queries
+    //! @{
 
     /**
     @brief Check if this inode represents a block device.
@@ -73,12 +72,39 @@ namespace kernel::filesystem
     */
     [[nodiscard]] auto is_character_device() const -> bool override;
 
+    //! @}
+
+    //! @name POSIX Information Access
+    //! @{
+
     [[nodiscard]] auto status() const -> kstd::result<kapi::filesystem::file_status> override;
 
     [[nodiscard]] auto raw_device() const -> std::optional<kapi::filesystem::device_number> override;
 
+    //! @}
+
+    //! @name Device Access
+    //! @{
+
+    /**
+    @brief Get the associated device.
+    @return A reference to the associated device.
+    */
+    [[nodiscard]] auto device() const -> kstd::shared_ptr<kapi::devices::device> const &;
+
+    //! @}
+
   private:
+    //! The handle to the device represented by this inode.
+    //!
+    //! Any I/O operations will be redirected to this device, allowing for filesystem based device I/O operations.
     kstd::shared_ptr<kapi::devices::device> m_device;
+
+    //! The original inode this inode was reconstituted from, if any.
+    //!
+    //! If this inode was reconstituted from a filesystem inode representing a device, e.g. from an ext2 block device
+    //! inode, Some queries must be forwarded to that origin inode. This data member will be used to forward those call
+    //! when applicable.
     kstd::shared_ptr<inode> m_origin;
   };
 }  // namespace kernel::filesystem
diff --git a/kernel/kernel/filesystem/ext2/filesystem.hpp b/kernel/kernel/filesystem/ext2/filesystem.hpp
index d7132f39..7124553d 100644
--- a/kernel/kernel/filesystem/ext2/filesystem.hpp
+++ b/kernel/kernel/filesystem/ext2/filesystem.hpp
@@ -78,6 +78,7 @@ namespace kernel::filesystem::ext2
     @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,
diff --git a/kernel/kernel/filesystem/ext2/inode.hpp b/kernel/kernel/filesystem/ext2/inode.hpp
index 7937c643..88596e3c 100644
--- a/kernel/kernel/filesystem/ext2/inode.hpp
+++ b/kernel/kernel/filesystem/ext2/inode.hpp
@@ -58,7 +58,6 @@ namespace kernel::filesystem::ext2
     @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.
-    @param size Number of bytes requested.
     @return Number of bytes read.
     */
     [[nodiscard]] auto read(std::span<std::byte> buffer, kstd::bytes offset) const
@@ -68,7 +67,6 @@ namespace kernel::filesystem::ext2
     @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.
-    @param size Number of bytes requested.
     @return Number of bytes written.
     */
     auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> override;
diff --git a/kernel/kernel/filesystem/inode.hpp b/kernel/kernel/filesystem/inode.hpp
index f0fbf689..12be39b4 100644
--- a/kernel/kernel/filesystem/inode.hpp
+++ b/kernel/kernel/filesystem/inode.hpp
@@ -12,7 +12,11 @@
 
 namespace kernel::filesystem
 {
-  //! Represents an inode in the filesystem.
+  //! An inode in the filesystem.
+  //!
+  //! Specific filesystems, or other subsystems, may provide their own implementation of this abstract base class. For
+  //! example, the ext2 filesystem provides its own inode implementation derived from this class, performing ext2
+  //! specific operations to fulfill the contract of this class.
   struct inode
   {
     //! Create an inode.
@@ -21,53 +25,72 @@ namespace kernel::filesystem
     //! Virtual destructor for the inode.
     virtual ~inode() = default;
 
+    //! @name I/O Operations
+    //! @{
+
     //! Read from this inode into a buffer
     //!
+    //! This function reads data from this inode into a given buffer. Implementations must guarantee, that if buffer is
+    //! larger than the entity represented by this inode, the buffer bytes beyond the range of the read bytes are left
+    //! untouched.
+    //!
     //! @param buffer Destination buffer.
     //! @param offset Read offset in bytes.
-    //! @param size Number of bytes requested.
     //! @return The number of bytes read on success, an error otherwise.
     [[nodiscard]] virtual auto read(std::span<std::byte> buffer, kstd::bytes offset) const
         -> kstd::result<kstd::bytes> = 0;
 
     //! Writes data from a buffer into this inode.
     //!
+    //! This function writes data from a buffer into this inode. Implementations must handle buffer sizes larger than
+    //! inode entity sizes gracefully. Specifically, all bytes in the buffer that do not fit into the entity represented
+    //! by this inode must be ignored.
+    //!
     //! @param buffer Source buffer.
     //! @param offset Write offset in bytes.
-    //! @param size Number of bytes to write.
     //! @return The number of bytes written on success, an error otherwise.
     virtual auto write(std::span<std::byte const> buffer, kstd::bytes offset) -> kstd::result<kstd::bytes> = 0;
 
-    //! Check if this inode is a directory.
-    //!
-    //! @return true iff. this inode is a directory, false otherwise.
-    [[nodiscard]] virtual auto is_directory() const -> bool;
+    //! @}
 
-    //! Check if this inode is a regular file.
-    //!
-    //! @return true iff. this inode is a regular file, false otherwise.
-    [[nodiscard]] virtual auto is_regular() const -> bool;
+    //! @name Property Checking
+    //! @{
 
-    //! Check if this inode is a block device node.
+    //! Check if this inode describes a block device node.
     //!
-    //! @return true iff. this inode is a block device node, false otherwise.
+    //! @return @c true iff. this inode describes a block device node, @c false otherwise.
     [[nodiscard]] virtual auto is_block_device() const -> bool;
 
-    //! Check if this inode is a character device node.
+    //! Check if this inode describes a character device node.
     //!
-    //! @return true iff. this inode is a character device node, false otherwise.
+    //! @return @c true iff. this inode describes a character device node, @c false otherwise.
     [[nodiscard]] virtual auto is_character_device() const -> bool;
 
-    //! Check if this inode is a device.
+    //! Check if this inode describes a device.
     //!
-    //! @return true iff. this inode is either a block or character device node, false otherwise.
+    //! @return @c true iff. this inode is either a block or character device node, @c false otherwise.
     [[nodiscard]] auto is_device() const -> bool;
 
-    //! Returns whether the inode is a symbolic link.
+    //! Check if this inode describes a directory.
+    //!
+    //! @return @c true iff. this inode describes a directory, @c false otherwise.
+    [[nodiscard]] virtual auto is_directory() const -> bool;
+
+    //! Check if this inode describes a regular file.
+    //!
+    //! @return @c true iff. this inode describes a regular file, @c false otherwise.
+    [[nodiscard]] virtual auto is_regular() const -> bool;
+
+    //! Check if this inode describes a symbolic link.
     //!
-    //! @return true iff. this inode is a symbolic link, false otherwise.
+    //! @return @c true iff. this inode describes a symbolic link, @c false otherwise.
     [[nodiscard]] virtual auto is_symbolic_link() const -> bool;
 
+    //! @}
+
+    //! @name POSIX Information Access
+    //! @{
+
     //! Get POSIX status information for this inode.
     //!
     //! @return a populated status information object, or an error or failure.
@@ -77,6 +100,8 @@ namespace kernel::filesystem
     //!
     //! @return a device number if this inode refers to a device, an empty optional otherwise.
     [[nodiscard]] virtual auto raw_device() const -> std::optional<kapi::filesystem::device_number>;
+
+    //! @}
   };
 }  // namespace kernel::filesystem
 
diff --git a/kernel/kernel/memory/bitmap_allocator.hpp b/kernel/kernel/memory/bitmap_allocator.hpp
index 370ce64d..a45638ef 100644
--- a/kernel/kernel/memory/bitmap_allocator.hpp
+++ b/kernel/kernel/memory/bitmap_allocator.hpp
@@ -21,7 +21,7 @@ namespace kernel::memory
     //! Construct a new, empty bitmap allocator.
     //!
     //! @param storage A contiguous region of virtual memory for state storage.
-    //! @param total_frame The total number of frames in the system.
+    //! @param frame_count The total number of frames in the system.
     bitmap_frame_allocator(std::span<std::uint64_t> storage, std::size_t frame_count) noexcept;
 
     bitmap_frame_allocator(bitmap_frame_allocator const &) = delete;
diff --git a/kernel/kernel/test_support/bump_frame_allocator.hpp b/kernel/kernel/test_support/bump_frame_allocator.hpp
index a8ffd486..c0a01ea8 100644
--- a/kernel/kernel/test_support/bump_frame_allocator.hpp
+++ b/kernel/kernel/test_support/bump_frame_allocator.hpp
@@ -43,7 +43,7 @@ namespace kernel::tests
     //! @copydoc kapi::memory::frame_allocator::release_many
     //!
     //! @note Due to the simple nature of this allocator, frames are never actually released.
-    auto release_many(std::pair<kapi::memory::frame, std::size_t>) -> void override {}
+    auto release_many([[maybe_unused]] std::pair<kapi::memory::frame, std::size_t> frame_set) -> void override {}
 
     //! The next free frame to be allocated.
     std::size_t next_free_frame{};
diff --git a/kernel/kernel/test_support/page_mapper.hpp b/kernel/kernel/test_support/page_mapper.hpp
index ee02217c..09c07f13 100644
--- a/kernel/kernel/test_support/page_mapper.hpp
+++ b/kernel/kernel/test_support/page_mapper.hpp
@@ -27,7 +27,7 @@ namespace kernel::tests
     //! @throws std::invalid_argument if the page has already been mapped.
     //! @throws std::runtime_error if the page cannot be mapped.
     //! @throws std::runtime_error if the underlying simulated memory cannot map the page.
-    auto map(kapi::memory::page page, kapi::memory::frame frame, flags) -> std::byte * override;
+    auto map(kapi::memory::page page, kapi::memory::frame frame, flags flags) -> std::byte * override;
 
     //! @copydoc kapi::memory::page_mapper::unmap
     //!