Improve Wasmer API intro docs

lib/api/src/exports.rs

@@ -59,6 +59,8 @@ pub enum ExportError {
 
 /// Exports is a special kind of map that allows easily unwrapping
 /// the types of instances.
+///
+/// TODO: add examples of using exports
 #[derive(Clone, Default)]
 pub struct Exports {
     map: Arc<IndexMap<String, Extern>>,

lib/api/src/externals/function.rs

@@ -52,7 +52,7 @@ pub enum FunctionDefinition {
 /// The module instance is used to resolve references to other definitions
 /// during execution of the function.
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#function-instances
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#function-instances>
 ///
 /// # Panics
 /// - Closures (functions with captured environments) are not currently supported

lib/api/src/externals/global.rs

@@ -15,7 +15,7 @@ use wasmer_vm::{Global as RuntimeGlobal, VMExportGlobal};
 /// A global instance is the runtime representation of a global variable.
 /// It consists of an individual value and a flag indicating whether it is mutable.
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#global-instances
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#global-instances>
 #[derive(Clone)]
 pub struct Global {
     store: Store,

lib/api/src/externals/memory.rs

@@ -22,7 +22,7 @@ use wasmer_vm::{Memory as RuntimeMemory, MemoryError, VMExportMemory};
 /// A memory created by the host or in WebAssembly code will be accessible and
 /// mutable from both host and WebAssembly.
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#memory-instances
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#memory-instances>
 #[derive(Debug, Clone)]
 pub struct Memory {
     store: Store,

lib/api/src/externals/mod.rs

@@ -22,7 +22,7 @@ use wasmer_engine::Export;
 /// An `Extern` is the runtime representation of an entity that
 /// can be imported or exported.
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#external-values
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#external-values>
 #[derive(Clone)]
 pub enum Extern {
     /// A external [`Function`].

lib/api/src/externals/table.rs

@@ -16,7 +16,7 @@ use wasmer_vm::{Table as RuntimeTable, VMCallerCheckedAnyfunc, VMExportTable};
 /// A table created by the host or in WebAssembly code will be accessible and
 /// mutable from both host and WebAssembly.
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#table-instances
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#table-instances>
 #[derive(Clone)]
 pub struct Table {
     store: Store,

lib/api/src/instance.rs

@@ -16,7 +16,7 @@ use wasmer_vm::{InstanceHandle, VMContext};
 /// functions, memories, tables and globals that allow
 /// interacting with WebAssembly.
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#module-instances
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#module-instances>
 #[derive(Clone)]
 pub struct Instance {
     handle: Arc<Mutex<InstanceHandle>>,

lib/api/src/lib.rs

@@ -1,4 +1,3 @@
-//! Wasmer API
 #![doc(
     html_logo_url = "https://github.com/wasmerio.png?size=200",
     html_favicon_url = "https://wasmer.io/static/icons/favicon.ico"
@@ -28,6 +27,199 @@
     )
 )]
 
+//! This crate contains the Wasmer API. The Wasmer API facilitates the efficient,
+//! sandboxed execution of [WebAssembly (Wasm)][wasm] modules.
+//!
+//! For examples of using the Wasmer API, check out the [wasmer examples][wasmer-examples].
+//!
+//! ---------
+//!
+//! # Table of Contents
+//!
+//! - [Project Layout](#project-layout)
+//!   - [Engines](#engines)
+//!   - [Compilers](#compilers)
+//! - [Features](#features)
+//! - [Wasm Primitives](#wasm-primitives)
+//!   - [Externs](#externs)
+//!     - [Functions](#functions)
+//!     - [Memories](#memories)
+//!     - [Globals](#globals)
+//!     - [Tables](#tables)
+//!
+//! ## Project Layout
+//!
+//! The Wasmer project is divided into a number of crates, below is a dependency
+//! graph with transitive dependencies removed.
+//!
+//! <div>
+//! <img src="https://raw.githubusercontent.com/wasmerio/wasmer/master/docs/deps_dedup.svg" />
+//! </div>
+//!
+//! While this crate is the top level API for Wasmer, we also publish crates built
+//! on top of this API that you may be interested in using, including:
+//!
+//! - [wasmer-cache][] for caching compiled Wasm modules.
+//! - [wasmer-emscripten][] for running Wasm modules compiled to the
+//!   Emscripten ABI.
+//! - [wasmer-wasi][] for running Wasm modules compiled to the WASI ABI.
+//!
+//! --------
+//!
+//! The Wasmer project has two major abstractions:
+//! - [Engines][wasmer-engine]
+//! - [Compilers][wasmer-compiler]
+//!
+//! These two abstractions have multiple options that can be enabled
+//! with features.
+//!
+//! ### Engines
+//!
+//! In the wasmer API, an engine is a system that uses a compiler to make
+//! a WebAssembly module executable.
+//!
+//! ### Compilers
+//!
+//! In the wasmer API, a compiler is a system that handles the details of
+//! making a Wasm module executable. For example, by generating native
+//! machine code for each Wasm function.
+//!
+//!
+//! ## Features
+//!
+//! This crate's features can be broken down into 2 kinds, features that
+//! enable new functionality and features that set defaults.
+//!
+//! The features that enable new functionality are:
+//! - `jit` - enable the JIT engine. (See [wasmer-jit][])
+//! - `native` - enable the native engine. (See [wasmer-native][])
+//! - `cranelift` - enable wasmer's Cranelift compiler. (See [wasmer-cranelift][])
+//! - `llvm` - enable wasmer's LLVM compiler. (See [wasmer-llvm][])
+//! - `singlepass` - enable wasmer's Singlepass compiler. (See [wasmer-singlepass][])
+//! - `wat` - enable wasmer to parse the WebAssembly text format.
+//!
+//! The features that set defaults come in sets that are mutually exclusive.
+//!
+//! The first set is the default compiler set:
+//! - `default-cranelift` - set wasmer's Cranelift compiler as the default.
+//! - `default-llvm` - set wasmer's LLVM compiler as the default.
+//! - `default-singlepass` - set wasmer's Singlepass compiler as the default.
+//!
+//! The next set is the default engine set:
+//! - `default-jit` - set the JIT engine as the default.
+//! - `default-native` - set the native engine as the default.
+//!
+//! --------
+//!
+//! By default the `wat`, `default-cranelift`, and `default-jit` features
+//! are enabled.
+//!
+//! # Wasm Primitives
+//! In order to make use of the power of the wasmer API, it's important
+//! to understand the primitives around which the API is built.
+//!
+//! Wasm only deals with a small number of core data types, these data
+//! types can be found in the [`Value`] type.
+//!
+//! In addition to the core Wasm types, the core types of the API are
+//! referred to as "externs".
+//!
+//! ## Externs
+//! An [`Extern`] is a type that can be imported or exported from a Wasm
+//! module.
+//!
+//! To import an extern, simply give it a namespace and a name with the
+//! [`imports`] macro:
+//!
+//! ```
+//! # use wasmer::{imports, Function, Memory, MemoryType, Store, ImportObject};
+//! # fn imports_example(store: &Store) -> ImportObject {
+//! let memory = Memory::new(&store, MemoryType::new(1, None, false)).unwrap();
+//! imports! {
+//!   "env" => {
+//!      "my_function" => Function::new_native(store, || println!("Hello")),
+//!      "memory" => memory,
+//!   }
+//! }
+//! # }
+//! ```
+//!
+//! And to access an exported extern, see the [`Exports`][] API, accessible
+//! from any instance via `instance.exports`:
+//!
+//! ```
+//! # use wasmer::{imports, Instance, Function, Memory, NativeFunc};
+//! # fn exports_example(instance: &Instance) -> anyhow::Result<()> {
+//! let memory = instance.exports.get_memory("memory")?;
+//! let memory: &Memory = instance.exports.get("some_other_memory")?;
+//! let add: NativeFunc<(i32, i32), i32> = instance.exports.get_native_function("add")?;
+//! let result = add.call(5, 37)?;
+//! assert_eq!(result, 42);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! These are the primary types that the wasmer API uses.
+//!
+//! ### Functions
+//! There are 2 types of functions in wasmer:
+//! - Wasm functions
+//! - Host functions
+//!
+//! A Wasm function is a function defined in a WebAssembly module that can
+//! only perform computation without side effects and call other functions.
+//!
+//! Wasm functions take 0 or more arguments and return 0 or more results.
+//! Wasm functions can only deal with the primitive types defined in
+//! [`Value`].
+//!
+//! A Host function is any function implemented on the host, in this case in
+//! Rust.
+//!
+//! Host functions can optionally be created with an enivronment that
+//! implements [`WasmerEnv`]. This enivronment is useful for maintaining
+//! host state (for example the filesystem in WASI).
+//!
+//! Thus WebAssembly modules by themselves cannot do anything but computation
+//! on the core types in [`Value`]. In order to make them more useful we
+//! give them access to the outside world with [`imports`].
+//!
+//! If you're looking for a sandboxed, POSIX-like environment to execute Wasm
+//! in, check out the [`wasmer-wasi`][] crate for our implementation of WASI,
+//! the WebAssembly System Interface.
+//!
+//! In the Wasmer API we support functions which take their arguments and
+//! return their results dynamically, [`Function`] and functions which
+//! take their arguments and return their results statically, [`NativeFunc`].
+//!
+//! ### Memories
+//! Memories store data.
+//!
+//! In most Wasm programs, nearly all data will live in a [`Memory`].
+//!
+//! This data can be shared between the host and guest to allow for more
+//! interesting programs.
+//!
+//! ### Globals
+//! A [`Global`] is a type that may be either mutable or immutable, and
+//! contains one of the core Wasm types defined in [`Value`].
+//!
+//! ### Tables
+//! A [`Table`] is an indexed list of items.
+//!
+//! [wasm]: https://webassembly.org/
+//! [wasmer-examples]: https://github.com/wasmerio/wasmer/tree/master/exmples
+//! [wasmer-cache]: https://docs.rs/wasmer-cache/1.0.0-beta1/wasmer_cache/
+//! [wasmer-compiler]: https://docs.rs/wasmer-compiler/1.0.0-beta1/wasmer_compiler/
+//! [wasmer-cranelift]: https://docs.rs/wasmer-cranelift/1.0.0-beta1/wasmer_cranelift/
+//! [wasmer-emscripten]: https://docs.rs/wasmer-emscripten/1.0.0-beta1/wasmer_emscripten/
+//! [wasmer-engine]: https://docs.rs/wasmer-engine/1.0.0-beta1/wasmer_engine/
+//! [wasmer-jit]: https://docs.rs/wasmer-jit/1.0.0-beta1/wasmer_jit/
+//! [wasmer-native]: https://docs.rs/wasmer-native/1.0.0-beta1/wasmer_native/
+//! [wasmer-singlepass]: https://docs.rs/wasmer-singlepass/1.0.0-beta1/wasmer_singlepass/
+//! [wasmer-llvm]: https://docs.rs/wasmer-llvm/1.0.0-beta1/wasmer_llvm/
+//! [wasmer-wasi]: https://docs.rs/wasmer-wasi/1.0.0-beta1/wasmer_wasi/
+
 mod env;
 mod exports;
 mod externals;
@@ -41,8 +233,12 @@ mod tunables;
 mod types;
 mod utils;
 
+/// Implement [`WasmerEnv`] for your type with `#[derive(WasmerEnv)]`.
+///
+/// See the [`WasmerEnv`] trait for more information.
 pub use wasmer_derive::WasmerEnv;
 
+#[doc(hidden)]
 pub mod internals {
     //! We use the internals module for exporting types that are only
     //! intended to use in internal crates such as the compatibility crate
@@ -92,7 +288,7 @@ pub use wasmer_types::{
 // TODO: should those be moved into wasmer::vm as well?
 pub use wasmer_vm::{raise_user_trap, MemoryError, VMExport};
 pub mod vm {
-    //! We use the vm module for re-exporting wasmer-vm types
+    //! The vm module re-exports wasmer-vm types.
 
     pub use wasmer_vm::{
         Memory, MemoryError, MemoryStyle, Table, TableStyle, VMMemoryDefinition, VMTableDefinition,

lib/api/src/store.rs

@@ -15,7 +15,7 @@ use wasmer_engine::Tunables as BaseTunables;
 /// the Wasm bytes into a valid module artifact), in addition to the
 /// [`Tunables`] (that are used to create the memories, tables and globals).
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#store
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#store>
 #[derive(Clone)]
 pub struct Store {
     engine: Arc<dyn Engine + Send + Sync>,

lib/api/src/types.rs

@@ -13,7 +13,7 @@ pub use wasmer_types::{
 /// * Floating-point (32 or 64 bit width)
 /// * Vectors (128 bits, with 32 or 64 bit lanes)
 ///
-/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#values
+/// Spec: <https://webassembly.github.io/spec/core/exec/runtime.html#values>
 pub type Val = Value<Function>;
 
 impl StoreObject for Val {