add documentation, refactoring

2 files changed, 61 insertions, 9 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
diff --git a/kernel/kapi/filesystem.cpp b/kernel/kapi/filesystem.cpp
index c8d4c6d..741875a 100644
--- a/kernel/kapi/filesystem.cpp
+++ b/kernel/kapi/filesystem.cpp
@@ -42,14 +42,14 @@ namespace kapi::filesystem
     return -1;
   }
 
-  auto close(int fd) -> int
+  auto close(int file_descriptor) -> int
   {
-    return kernel::filesystem::file_descriptor_table::get().remove_file(fd);
+    return kernel::filesystem::file_descriptor_table::get().remove_file(file_descriptor);
   }
 
-  auto read(int fd, void * buffer, size_t size) -> ssize_t
+  auto read(int file_descriptor, void * buffer, size_t size) -> ssize_t
   {
-    if (auto open_file_description = kernel::filesystem::file_descriptor_table::get().get_file(fd))
+    if (auto open_file_description = kernel::filesystem::file_descriptor_table::get().get_file(file_descriptor))
     {
       return open_file_description->read(buffer, size);
     }
@@ -57,9 +57,9 @@ namespace kapi::filesystem
     return -1;
   }
 
-  auto write(int fd, void const * buffer, size_t size) -> ssize_t
+  auto write(int file_descriptor, void const * buffer, size_t size) -> ssize_t
   {
-    if (auto open_file_description = kernel::filesystem::file_descriptor_table::get().get_file(fd))
+    if (auto open_file_description = kernel::filesystem::file_descriptor_table::get().get_file(file_descriptor))
     {
       return open_file_description->write(buffer, size);
     }