kapi/fs: normalize doc comments

1 files changed, 48 insertions, 59 deletions

diff --git a/kapi/kapi/filesystem.hpp b/kapi/kapi/filesystem.hpp
index 316e5407..0f092d29 100644
--- a/kapi/kapi/filesystem.hpp
+++ b/kapi/kapi/filesystem.hpp
@@ -9,83 +9,72 @@
 #include <span>
 #include <string_view>
 
+//! The interface for filesystem operations in the kernel.
+//!
+//! It includes functions for mounting and unmounting filesystems, as well as basic file operations such as opening,
+//! closing, reading from, and writing to files. The actual implementation of these functions is in the kernel's
+//! filesystem subsystem, which will handle the specifics of different filesystem types and their interactions with the
+//! underlying storage devices.
 namespace kapi::filesystem
 {
-  /**
-  @brief The kapi::filesystem namespace provides the interface for filesystem operations in the kernel. It includes
-  functions for mounting and unmounting filesystems, as well as basic file operations such as opening, closing, reading
-  from, and writing to files. The actual implementation of these functions is in the kernel's  filesystem subsystem,
-  which will handle the specifics of different filesystem types and their interactions with the underlying storage
-  devices.
-  */
+  //! @addtogroup kapi-filesystem-kernel-defined
+  //! @{
 
-  /**
-  @brief Mounts a filesystem from the specified @p source at the specified @p target path.
-  @param source The source device or filesystem to mount.
-  @param target The target mount point.
-  @return Nothing on success, an error code otherwise.
-  @qualifier kernel-defined
-  */
+  //! Mount a filesystem at the specified source path onto the specified target path.
+  //!
+  //! @param source The source device or filesystem to mount.
+  //! @param target The target mount point.
+  //! @return Nothing on success, an error code otherwise.
   auto mount(std::string_view source, std::string_view target) -> std::expected<void, kstd::error_code>;
 
-  /**
-  @brief Unmounts a filesystem from the specified @p target path.
-  @param target The target mount point to unmount.
-  @return Nothing on success, an error code otherwise.
-  @qualifier kernel-defined
-  */
+  //! Unmount a filesystem from the specified target path.
+  //!
+  //! @param target The target mount point to unmount.
+  //! @return Nothing on success, an error code otherwise.
   auto umount(std::string_view target) -> std::expected<void, kstd::error_code>;
 
-  /**
-  @brief Opens a file at the specified @p path.
-  @param path The path to the file to open.
-  @return A file descriptor on success, an error code otherwise.
-  @qualifier kernel-defined
-  */
+  //! Open a file at the specified path.
+  //!
+  //! @param path The path to the file to open.
+  //! @return A file descriptor on success, an error code otherwise.
   auto open(std::string_view path) -> std::expected<std::size_t, kstd::error_code>;
 
-  /**
-  @brief Closes a @p file_descriptor.
-  @param file_descriptor The file descriptor to close.
-  @return Nothing on success, an error code otherwise .
-  @qualifier kernel-defined
-  */
+  //! Close a file descriptor.
+  //!
+  //! @param file_descriptor The file descriptor to close.
+  //! @return Nothing on success, an error code otherwise .
   auto close(size_t file_descriptor) -> std::expected<void, kstd::error_code>;
 
-  /**
-  @brief Reads @p size bytes into @p buffer from a @p file_descriptor.
-  @param file_descriptor The file descriptor to read from.
-  @param buffer The buffer to store the read data.
-  @return The number of bytes read on success, an error code otherwise.
-  @qualifier kernel-defined
-  */
+  //! Read bytes from a file into a given buffer.
+  //!
+  //! @param file_descriptor The file descriptor to read from.
+  //! @param buffer The buffer to store the read data.
+  //! @return The number of bytes read on success, an error code otherwise.
   auto read(size_t file_descriptor, std::span<std::byte> buffer) -> std::expected<std::size_t, kstd::error_code>;
 
-  /**
-  @brief Writes @p size bytes from @p buffer to a @p file_descriptor.
-  @param file_descriptor The file descriptor to write to.
-  @param buffer The buffer containing the data to write.
-  @return The number of bytes written on success, an error code otherwise.
-  @qualifier kernel-defined
-  */
+  //! Write bytes from a given buffer to a file descriptor.
+  //!
+  //! @param file_descriptor The file descriptor to write to.
+  //! @param buffer The buffer containing the data to write.
+  //! @return The number of bytes written on success, an error code otherwise.
   auto write(size_t file_descriptor, std::span<std::byte const> buffer) -> std::expected<std::size_t, kstd::error_code>;
 
-  /**
-  @brief Creates a new directory at the specified @p path.
-  @param path The path where the new directory should be created.
-  @return 0 on success, -1 on failure.
-  @qualifier kernel-defined
-  */
+  //! 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 on failure.
   auto mkdir(std::string_view path) -> kstd::result<void>;
 
-  /**
-  @brief Creates a new file at the specified @p path.
-  @param path The path where the new file should be created.
-  @return 0 on success, -1 on failure.
-  @qualifier kernel-defined
-  */
-  // TODO remove again after the open method supports an optional create flag
+  //! Create a new file at the specified path.
+  //!
+  //! @deprecated this function is deprecated and slated for removal once kapi::filesystem::open supports the create
+  //! flag.
+  //!
+  //! @param path The path where the new file should be created.
+  //! @return Nothing on success, an error on failure.
   auto create(std::string_view path) -> kstd::result<void>;
+
+  //! @}
 }  // namespace kapi::filesystem
 
 #endif  // TEACHOS_KAPI_FILESYSTEM_HPP
\ No newline at end of file