Document design rationale for resolve_path return type

1 files changed, 10 insertions, 0 deletions

diff --git a/kernel/include/kernel/filesystem/vfs.hpp b/kernel/include/kernel/filesystem/vfs.hpp
index 2aa1dd7..7a6ebf9 100644
--- a/kernel/include/kernel/filesystem/vfs.hpp
+++ b/kernel/include/kernel/filesystem/vfs.hpp
@@ -79,6 +79,16 @@ namespace kernel::filesystem
     vfs() = default;
     auto init_internal() -> void;
 
+    /**
+     * 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)
         -> std::pair<kstd::shared_ptr<dentry>, kstd::shared_ptr<mount>>;
     [[nodiscard]] auto resolve_path(std::string_view path) -> kstd::shared_ptr<dentry>;