Improve wasmfs API doc comments and return types (emscripten-core#16267)

Update the return types of `wasmfs_create_file` and `wasmfs_create_directory` to
match the return types of `open` and `mkdir`, respectively, and document that
they have similar behavior to those functions.

Author: tlively

system/include/emscripten/wasmfs.h

@@ -22,11 +22,15 @@ backend_t wasmfs_get_backend_by_path(char* path);
 // Obtains the backend_t of a specified fd.
 backend_t wasmfs_get_backend_by_fd(int fd);
 
-// Creates a new file in the new file system under a specific backend.
-uint32_t wasmfs_create_file(char* pathname, mode_t mode, backend_t backend);
+// Creates and opens a new file in the new file system under a specific backend.
+// Returns the file descriptor for the new file like `open`. Returns a negative
+// value on error. TODO: It might be worth returning a more specialized type
+// like __wasi_fd_t here.
+int wasmfs_create_file(char* pathname, mode_t mode, backend_t backend);
 
 // Creates a new directory in the new file system under a specific backend.
-long wasmfs_create_directory(char* path, long mode, backend_t backend);
+// Returns 0 on success like `mkdir`, or a negative value on error.
+int wasmfs_create_directory(char* path, long mode, backend_t backend);
 
 // Backend creation
 

system/lib/wasmfs/syscalls.cpp

@@ -429,7 +429,9 @@ static __wasi_fd_t doOpen(char* pathname,
 
 // This function is exposed to users and allows users to create a file in a
 // specific backend. An fd to an open file is returned.
-__wasi_fd_t wasmfs_create_file(char* pathname, mode_t mode, backend_t backend) {
+int wasmfs_create_file(char* pathname, mode_t mode, backend_t backend) {
+  static_assert(std::is_same_v<decltype(doOpen(0, 0, 0, 0)), unsigned int>,
+                "unexpected conversion from result of doOpen to int");
   return doOpen(pathname, O_CREAT, mode, backend);
 }
 
@@ -491,7 +493,9 @@ static long doMkdir(char* path, long mode, backend_t backend = NullBackend) {
 
 // This function is exposed to users and allows users to specify a particular
 // backend that a directory should be created within.
-long wasmfs_create_directory(char* path, long mode, backend_t backend) {
+int wasmfs_create_directory(char* path, long mode, backend_t backend) {
+  static_assert(std::is_same_v<decltype(doMkdir(0, 0, 0)), long>,
+                "unexpected conversion from result of doMkdir to int");
   return doMkdir(path, mode, backend);
 }