Merge #841

841: Add lots of rustdocs and clean up one line of code r=MarkMcCaskey a=MarkMcCaskey



- [x] Add a short description of the the change to the CHANGELOG.md file


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

CHANGELOG.md

@@ -6,6 +6,8 @@ Blocks of changes will separated by version increments.
 
 ## **[Unreleased]**
 
+- [#841](https://github.com/wasmerio/wasmer/pull/841) Slightly improve rustdoc documentation and small updates to outdated info in readme files
+- [#835](https://github.com/wasmerio/wasmer/pull/836) Update Cranelift fork version to `0.44.0`
 - [#836](https://github.com/wasmerio/wasmer/pull/836) Update Cranelift fork version to `0.44.0`
 - [#839](https://github.com/wasmerio/wasmer/pull/839) Change supported version to stable Rust 1.37+
 - [#834](https://github.com/wasmerio/wasmer/pull/834) Fix panic when unwraping `wasmer` arguments

lib/runtime-c-api/README.md

@@ -25,7 +25,7 @@
 # Wasmer Runtime C API
 
 Wasmer is a standalone JIT WebAssembly runtime, aiming to be fully
-compatible with Emscripten, Rust and Go. [Learn
+compatible with WASI, Emscripten, Rust and Go. [Learn
 more](https://github.com/wasmerio/wasmer).
 
 This crate exposes a C and a C++ API for the Wasmer runtime.

lib/runtime-core/README.md

@@ -25,7 +25,8 @@
 # Wasmer Runtime Core
 
 Wasmer is a standalone JIT WebAssembly runtime, aiming to be fully
-compatible with Emscripten, Rust and Go. [Learn
+compatible with WASI, Emscripten, Rust and Go. [Learn
 more](https://github.com/wasmerio/wasmer).
 
-This crate represents the core of the runtime.
+This crate represents the core of the runtime.  Consider
+[`wasmer-runtime`] for higher level APIs.

lib/runtime-core/src/backend.rs

@@ -22,6 +22,7 @@ pub mod sys {
 }
 pub use crate::sig_registry::SigRegistry;
 
+/// Enum used to select which compiler should be used to generate code.
 #[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)]
 pub enum Backend {
     Cranelift,
@@ -30,6 +31,7 @@ pub enum Backend {
 }
 
 impl Backend {
+    /// Get a list of the currently enabled (via feature flag) backends.
     pub fn variants() -> &'static [&'static str] {
         &[
             #[cfg(feature = "backend-cranelift")]
@@ -41,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",
@@ -111,6 +113,7 @@ impl Default for MemoryBoundCheckMode {
     }
 }
 
+/// Controls which experimental features will be enabled.
 #[derive(Debug, Default)]
 pub struct Features {
     pub simd: bool,

lib/runtime-core/src/backing.rs

@@ -618,7 +618,7 @@ fn import_functions(
         }
     }
 
-    if link_errors.len() > 0 {
+    if !link_errors.is_empty() {
         Err(link_errors)
     } else {
         Ok(functions.into_boxed_map())

lib/runtime/README.md

@@ -95,11 +95,16 @@ fn main() -> error::Result<()> {
 ## Additional Notes
 
 The `wasmer-runtime` crate is build to support multiple compiler
-backends.  Currently, we support the [Cranelift] compiler with the
-[`wasmer-clif-backend`] crate by default.
+backends.  We support have a [Cranelift] backend in the
+[`wasmer-clif-backend`] crate, a [LLVM] backend in the
+[`wasmer-llvm-backend`] crate, and the [Singlepass] backend in the
+[`wasmer-singlepass-backend`] crate.  Currently, the Cranelift backend
+is the default.
 
 You can specify the compiler you wish to use with the [`compile_with`] function.
 
 [Cranelift]: https://github.com/CraneStation/cranelift
+[LLVM]: https://llvm.org
+[Singlepass]: https://github.com/wasmerio/wasmer/tree/master/lib/singlepass-backend
 [`wasmer-clif-backend`]: https://crates.io/crates/wasmer-clif-backend
 [`compile_with`]: https://docs.rs/wasmer-runtime/*/wasmer_runtime/fn.compile_with.html

lib/runtime/src/lib.rs

@@ -189,6 +189,10 @@ pub fn instantiate(wasm: &[u8], import_object: &ImportObject) -> error::Result<I
 }
 
 /// Get a single instance of the default compiler to use.
+///
+/// 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 {
     #[cfg(any(
         all(
@@ -219,6 +223,11 @@ pub fn default_compiler() -> impl Compiler {
     DefaultCompiler::new()
 }
 
+/// Get the `Compiler` as a trait object for the given `Backend`.
+/// 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()`.
 pub fn compiler_for_backend(backend: Backend) -> Option<Box<dyn Compiler>> {
     match backend {
         #[cfg(feature = "cranelift")]
@@ -241,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

@@ -10,6 +10,16 @@
 #![doc(html_favicon_url = "https://wasmer.io/static/icons/favicon.ico")]
 #![doc(html_logo_url = "https://avatars3.githubusercontent.com/u/44205449?s=200&v=4")]
 
+//! Wasmer's WASI implementation
+//!
+//! Use `generate_import_object` to create an `ImportObject`.  This `ImportObject`
+//! can be combined with a module to create an `Instance` which can execute WASI
+//! Wasm functions.
+//!
+//! See `state` for the experimental WASI FS API.  Also see the
+//! [WASI plugin example](https://github.com/wasmerio/wasmer/blob/master/examples/plugin.rs)
+//! for an example of how to extend WASI using the WASI FS API.
+
 #[cfg(target = "windows")]
 extern crate winapi;
 
@@ -37,6 +47,7 @@ pub struct ExitCode {
     pub code: syscalls::types::__wasi_exitcode_t,
 }
 
+/// 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

@@ -1,6 +1,17 @@
 //! WARNING: the API exposed here is unstable and very experimental.  Certain things are not ready
 //! yet and may be broken in patch releases.  If you're using this and have any specific needs,
 //! please let us know here https://github.com/wasmerio/wasmer/issues/583 or by filing an issue.
+//!
+//! Wasmer always has a virtual root directory located at `/` at which all pre-opened directories can
+//! be found.  It's possible to traverse between preopened directories this way as well (for example
+//! `preopen-dir1/../preopen-dir2`).
+//!
+//! A preopened directory is a directory or directory + name combination passed into the
+//! `generate_import_object` function.  These are directories that the caller has given
+//! the WASI module permission to access.
+//!
+//! You can implement `WasiFile` for your own types to get custom behavior and extend WASI, see the
+//! [WASI plugin example](https://github.com/wasmerio/wasmer/blob/master/examples/plugin.rs).
 
 mod types;
 
@@ -44,6 +55,8 @@ pub struct InodeVal {
     pub kind: Kind,
 }
 
+/// The core of the filesystem abstraction.  Includes directories,
+/// files, and symlinks.
 #[derive(Debug, Serialize, Deserialize)]
 pub enum Kind {
     File {
@@ -998,6 +1011,12 @@ impl WasiFs {
     }
 }
 
+/// 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,6 +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 that implements `WasiFile` and
+/// `Serialize` + `Deserialize`.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Stdout;
 impl Read for Stdout {
@@ -717,6 +719,8 @@ impl WasiFile for Stdout {
     }
 }
 
+/// A wrapper type around Stderr that implements `WasiFile` and
+/// `Serialize` + `Deserialize`.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Stderr;
 impl Read for Stderr {
@@ -808,6 +812,8 @@ impl WasiFile for Stderr {
     }
 }
 
+/// A wrapper type around Stdin that implements `WasiFile` and
+/// `Serialize` + `Deserialize`.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Stdin;
 impl Read for Stdin {