add documentation, refactoring

1 files changed, 55 insertions, 3 deletions

diff --git a/kapi/include/kapi/filesystem.hpp b/kapi/include/kapi/filesystem.hpp
index db77bda..94d42ce 100644
--- a/kapi/include/kapi/filesystem.hpp
+++ b/kapi/include/kapi/filesystem.hpp
@@ -8,14 +8,66 @@
 
 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.
+  */
+
+  /**
+  @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 0 on success, -1 on failure.
+  @qualifier kernel-defined
+  */
   auto mount(std::string_view source, std::string_view target) -> int;
+
+  /**
+  @brief Unmounts a filesystem from the specified @p target path.
+  @param target The target mount point to unmount.
+  @return 0 on success, -1 on failure.
+  @qualifier kernel-defined
+  */
   auto umount(std::string_view target) -> int;
 
+  /**
+  @brief Opens a file at the specified @p path.
+  @param path The path to the file to open.
+  @return A file descriptor on success, -1 on failure.
+  @qualifier kernel-defined
+  */
   auto open(std::string_view path) -> int;
-  auto close(int fd) -> int;
 
-  auto read(int fd, void * buffer, size_t size) -> ssize_t;
-  auto write(int fd, void const * buffer, size_t size) -> ssize_t;
+  /**
+  @brief Closes a @p file_descriptor.
+  @param file_descriptor The file descriptor to close.
+  @return 0 on success, -1 on failure.
+  @qualifier kernel-defined
+  */
+  auto close(int file_descriptor) -> int;
+
+  /**
+  @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.
+  @param size The number of bytes to read.
+  @return The number of bytes read on success, -1 on failure.
+  @qualifier kernel-defined
+  */
+  auto read(int file_descriptor, void * buffer, size_t size) -> ssize_t;
+
+  /**
+  @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.
+  @param size The number of bytes to write.
+  @return The number of bytes written on success, -1 on failure.
+  @qualifier kernel-defined
+  */
+  auto write(int file_descriptor, void const * buffer, size_t size) -> ssize_t;
 }  // namespace kapi::filesystem
 
 #endif  // TEACHOS_KAPI_FILESYSTEM_HPP
\ No newline at end of file