Add docs

1 files changed, 34 insertions, 1 deletions

diff --git a/lib/std/fs/wasi.zig b/lib/std/fs/wasi.zig
index 0c179a3df2..21107c2094 100644
--- a/lib/std/fs/wasi.zig
+++ b/lib/std/fs/wasi.zig
@@ -5,18 +5,30 @@ const Allocator = mem.Allocator;
 
 usingnamespace std.os.wasi;
 
+/// Type of WASI preopen.
+///
+/// WASI currently offers only `Dir` as a valid preopen resource.
 pub const PreopenType = enum {
     Dir,
 };
 
+/// WASI preopen struct. This struct consists of a WASI file descriptor
+/// and type of WASI preopen. It can be obtained directly from the WASI
+/// runtime using `PreopenList.populate()` method.
 pub const Preopen = struct {
+    /// WASI file descriptor.
     fd: fd_t,
+
+    /// Type of the preopen.
     @"type": union(PreopenType) {
+        /// Path to a preopened directory.
         Dir: []const u8,
     },
 
     const Self = @This();
 
+    /// Construct new `Preopen` instance of type `PreopenType.Dir` from
+    /// WASI file descriptor and WASI path.
     pub fn newDir(fd: fd_t, path: []const u8) Self {
         return Self{
             .fd = fd,
@@ -25,18 +37,29 @@ pub const Preopen = struct {
     }
 };
 
+/// Dynamically-sized array list of WASI preopens. This struct is a
+/// convenience wrapper for issuing `std.os.wasi.fd_prestat_get` and
+/// `std.os.wasi.fd_prestat_dir_name` syscalls to the WASI runtime, and
+/// collecting the returned preopens.
+///
+/// This struct is intended to be used in any WASI program which intends
+/// to use the capabilities as passed on by the user of the runtime.
 pub const PreopenList = struct {
     const InnerList = std.ArrayList(Preopen);
 
+    /// Internal dynamically-sized buffer for storing the gathered preopens.
     buffer: InnerList,
 
     const Self = @This();
+
     pub const Error = os.UnexpectedError || Allocator.Error;
 
+    /// Deinitialize with `deinit`.
     pub fn init(allocator: *Allocator) Self {
         return Self{ .buffer = InnerList.init(allocator) };
     }
 
+    /// Release all allocated memory.
     pub fn deinit(pm: Self) void {
         for (pm.buffer.items) |preopen| {
             switch (preopen.@"type") {
@@ -46,6 +69,8 @@ pub const PreopenList = struct {
         pm.buffer.deinit();
     }
 
+    /// Populate the list with the preopens by issuing `std.os.wasi.fd_prestat_get`
+    /// and `std.os.wasi.fd_prestat_dir_name` syscalls to the runtime.
     pub fn populate(self: *Self) Error!void {
         errdefer self.deinit();
         var fd: fd_t = 3; // start fd has to be beyond stdio fds
@@ -77,6 +102,12 @@ pub const PreopenList = struct {
         }
     }
 
+    /// Find preopen by path. If the preopen exists, return it.
+    /// Otherwise, return `null`.
+    ///
+    /// TODO make the function more generic by searching by `PreopenType` union. This will
+    /// be needed in the future when WASI extends its capabilities to resources
+    /// other than preopened directories.
     pub fn find(self: *const Self, path: []const u8) ?*const Preopen {
         for (self.buffer.items) |preopen| {
             switch (preopen.@"type") {
@@ -88,12 +119,14 @@ pub const PreopenList = struct {
         return null;
     }
 
+    /// Return the inner buffer as read-only slice.
     pub fn asSlice(self: *const Self) []const Preopen {
         return self.buffer.items;
     }
 };
 
-pub fn openat(dir_fd: fd_t, file_path: []const u8, oflags: oflags_t, fdflags: fdflags_t, rights: rights_t) std.os.OpenError!fd_t {
+/// Convenience wrapper for `std.os.wasi.path_open` syscall.
+pub fn openat(dir_fd: fd_t, file_path: []const u8, oflags: oflags_t, fdflags: fdflags_t, rights: rights_t) os.OpenError!fd_t {
     var fd: fd_t = undefined;
     switch (path_open(dir_fd, 0x0, file_path.ptr, file_path.len, oflags, rights, 0x0, fdflags, &fd)) {
         0 => {},