Improve docs from feedback

lib/runtime-core/src/backend.rs

@@ -22,7 +22,7 @@ pub mod sys {
 }
 pub use crate::sig_registry::SigRegistry;
 
-/// Enum used to select which compiler should be used to generate code
+/// Enum used to select which compiler should be used to generate code.
 #[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)]
 pub enum Backend {
     Cranelift,
@@ -31,7 +31,7 @@ pub enum Backend {
 }
 
 impl Backend {
-    /// Get a list of the currently enabled (via feature flag) backends
+    /// Get a list of the currently enabled (via feature flag) backends.
     pub fn variants() -> &'static [&'static str] {
         &[
             #[cfg(feature = "backend-cranelift")]
@@ -43,8 +43,8 @@ impl Backend {
         ]
     }
 
-    /// Stable string representation of the backend
-    /// can be used as part of a cache key, for example
+    /// Stable string representation of the backend.
+    /// It can be used as part of a cache key, for example.
     pub fn to_string(&self) -> &'static str {
         match self {
             Backend::Cranelift => "cranelift",
@@ -113,7 +113,7 @@ impl Default for MemoryBoundCheckMode {
     }
 }
 
-/// Controls which experimental features will be enabled
+/// Controls which experimental features will be enabled.
 #[derive(Debug, Default)]
 pub struct Features {
     pub simd: bool,

lib/runtime/src/lib.rs

@@ -190,7 +190,7 @@ pub fn instantiate(wasm: &[u8], import_object: &ImportObject) -> error::Result<I
 
 /// Get a single instance of the default compiler to use.
 ///
-/// The ouptput of this function can be controlled by the mutually
+/// The output of this function can be controlled by the mutually
 /// exclusive `default-backend-llvm`, `default-backend-singlepass`,
 /// and `default-backend-cranelift` feature flags.
 pub fn default_compiler() -> impl Compiler {
@@ -224,10 +224,10 @@ pub fn default_compiler() -> impl Compiler {
 }
 
 /// Get the `Compiler` as a trait object for the given `Backend`.
-/// Returns `Option` because support for the `Compiler` may not be enabled by
-/// feature flags.
+/// Returns `Option` because support for the requested `Compiler` may
+/// not be enabled by feature flags.
 ///
-/// To get a list of the enabled backends as strings, call `Backend::variants()`
+/// To get a list of the enabled backends as strings, call `Backend::variants()`.
 pub fn compiler_for_backend(backend: Backend) -> Option<Box<dyn Compiler>> {
     match backend {
         #[cfg(feature = "cranelift")]
@@ -250,5 +250,5 @@ pub fn compiler_for_backend(backend: Backend) -> Option<Box<dyn Compiler>> {
     }
 }
 
-/// The current version of this crate
+/// The current version of this crate.
 pub const VERSION: &str = env!("CARGO_PKG_VERSION");

lib/wasi/src/lib.rs

@@ -47,7 +47,7 @@ pub struct ExitCode {
     pub code: syscalls::types::__wasi_exitcode_t,
 }
 
-/// Create a WasiImport object with `WasiState`
+/// Creates a WasiImport object with `WasiState`.
 pub fn generate_import_object(
     args: Vec<Vec<u8>>,
     envs: Vec<Vec<u8>>,

lib/wasi/src/state/mod.rs

@@ -55,7 +55,8 @@ pub struct InodeVal {
     pub kind: Kind,
 }
 
-/// The core file-object data type
+/// The core of the filesystem abstraction.  Includes directories,
+/// files, and symlinks.
 #[derive(Debug, Serialize, Deserialize)]
 pub enum Kind {
     File {
@@ -1010,7 +1011,12 @@ impl WasiFs {
     }
 }
 
-/// Top level data type containing all the state that WASI can interact with
+/// Top level data type containing all* the state with which WASI can
+/// interact.
+///
+/// * The contents of files are not stored and may be modified by
+/// other, concurrently running programs.  Data such as the contents
+/// of directories are lazily loaded.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct WasiState {
     pub fs: WasiFs,

lib/wasi/src/state/types.rs

@@ -626,7 +626,8 @@ fn host_file_bytes_available(_raw_fd: i32) -> Result<usize, WasiFsError> {
     unimplemented!("host_file_bytes_available not yet implemented for non-Unix-like targets.  This probably means the program tried to use wasi::poll_oneoff")
 }
 
-/// A wrapper type around Stdout
+/// A wrapper type around Stdout that implements `WasiFile` and
+/// `Serialize` + `Deserialize`.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Stdout;
 impl Read for Stdout {
@@ -718,7 +719,8 @@ impl WasiFile for Stdout {
     }
 }
 
-/// A wrapper type around Stderr
+/// A wrapper type around Stderr that implements `WasiFile` and
+/// `Serialize` + `Deserialize`.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Stderr;
 impl Read for Stderr {
@@ -810,7 +812,8 @@ impl WasiFile for Stderr {
     }
 }
 
-/// A wrapper type around Stdin
+/// A wrapper type around Stdin that implements `WasiFile` and
+/// `Serialize` + `Deserialize`.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Stdin;
 impl Read for Stdin {