Merge #1063

1063: Add more doc comments to our WASI implementation r=MarkMcCaskey a=MarkMcCaskey



Co-authored-by: Mark McCaskey <mark@wasmer.io>

lib/wasi/src/state/builder.rs

@@ -1,4 +1,4 @@
-//! Builder code for [`WasiState`]
+//! Builder system for configuring a [`WasiState`] and creating it.
 
 use crate::state::{WasiFs, WasiState};
 use std::path::{Path, PathBuf};

lib/wasi/src/state/mod.rs

@@ -376,6 +376,7 @@ impl WasiFs {
         }
     }
 
+    /// Returns the next available inode index for creating a new inode.
     fn get_next_inode_index(&mut self) -> u64 {
         let next = self.inode_counter.get();
         self.inode_counter.set(next + 1);
@@ -491,6 +492,19 @@ impl WasiFs {
         }
     }
 
+    /// Internal part of the core path resolution function which implements path
+    /// traversal logic such as resolving relative path segments (such as
+    /// `.` and `..`) and resolving symlinks (while preventing infinite
+    /// loops/stack overflows).
+    ///
+    /// TODO: expand upon exactly what the state of the returned value is,
+    /// explaining lazy-loading from the real file system and synchronizing
+    /// between them.
+    ///
+    /// This is where a lot of the magic happens, be very careful when editing
+    /// this code.
+    ///
+    /// TODO: write more tests for this code
     fn get_inode_at_path_inner(
         &mut self,
         base: __wasi_fd_t,
@@ -672,6 +686,14 @@ impl WasiFs {
         Ok(cur_inode)
     }
 
+    /// Splits a path into the first preopened directory that is a parent of it,
+    /// if such a preopened directory exists, and the rest of the path.
+    ///
+    /// NOTE: this behavior seems to be not the same as what libpreopen is
+    /// doing in WASI.
+    ///
+    /// TODO: evaluate users of this function and explain why this behavior is
+    /// not the same as libpreopen or update its behavior to be the same.
     fn path_into_pre_open_and_relative_path(
         &self,
         path: &Path,