Added spec docs to app API public objects

lib/api/src/externals/function.rs

@@ -38,6 +38,14 @@ pub enum FunctionDefinition {
 }
 
 /// A WebAssembly `function`.
+///
+/// A function instance is the runtime representation of a function.
+/// It effectively is a closure of the original function over the runtime
+/// `Instance` of its originating `Module`. 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
 #[derive(Clone, PartialEq)]
 pub struct Function {
     pub(crate) store: Store,
@@ -46,7 +54,7 @@ pub struct Function {
 }
 
 impl Function {
-    /// Creates a new `Function` that is:
+    /// Creates a new host `Function` that is:
     ///
     /// 1. Static/Monomorphic, i.e. all inputs and outputs have a
     ///    unique _statically declared type_. The outputs can be
@@ -77,7 +85,7 @@ impl Function {
         }
     }
 
-    /// Creates a new `Function` that is:
+    /// Creates a new host `Function` that is:
     ///
     /// 1. Static/Monomorphic, i.e. all inputs and outputs have a
     ///    unique statically declared type. The outputs can be wrapped
@@ -115,7 +123,7 @@ impl Function {
         }
     }
 
-    /// Creates a new `Function` that is:
+    /// Creates a new host `Function` that is:
     ///
     /// 1. Dynamic/Polymorphic, i.e. all inputs are received in a
     ///    slice of `Val` (the set of all Wasm values), and all
@@ -150,7 +158,7 @@ impl Function {
         }
     }
 
-    /// Creates a new `Function` that is:
+    /// Creates a new host `Function` that is:
     ///
     /// 1. Dynamic/Polymorphic, i.e. all inputs are received in a
     ///    slice of `Val` (the set of all Wasm values), and all
@@ -187,11 +195,12 @@ impl Function {
         }
     }
 
-    /// Returns the underlying type of this function.
+    /// Returns the underlying [`FunctionType`] corresponding to this runtime `Function`.
     pub fn ty(&self) -> &FunctionType {
         &self.exported.signature
     }
 
+    /// Returns the [`Store`] that owns this `Function`.
     pub fn store(&self) -> &Store {
         &self.store
     }

lib/api/src/externals/global.rs

@@ -8,6 +8,12 @@ use crate::RuntimeError;
 use std::fmt;
 use wasmer_vm::{Export, ExportGlobal, VMGlobalDefinition};
 
+/// A WebAssembly `global`.
+///
+/// A global instance is the runtime representation of a global variable.
+/// It holds an individual value and a flag indicating whether it is mutable.
+///
+/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#global-instances
 #[derive(Clone)]
 pub struct Global {
     store: Store,
@@ -15,12 +21,14 @@ pub struct Global {
 }
 
 impl Global {
+    /// Create a new `Global` with the initial value [`Val`].
     pub fn new(store: &Store, val: Val) -> Global {
         // Note: we unwrap because the provided type should always match
         // the value type, so it's safe to unwrap.
         Self::from_type(store, GlobalType::new(val.ty(), Mutability::Const), val).unwrap()
     }
 
+    /// Create a mutable `Global` with the initial value [`Val`].
     pub fn new_mut(store: &Store, val: Val) -> Global {
         // Note: we unwrap because the provided type should always match
         // the value type, so it's safe to unwrap.
@@ -52,14 +60,17 @@ impl Global {
         })
     }
 
+    /// Returns the underlying [`GlobalType`] corresponding to this runtime `Global`.
     pub fn ty(&self) -> &GlobalType {
         &self.exported.global
     }
 
+    /// Returns the [`Store`] that owns this `Global`.
     pub fn store(&self) -> &Store {
         &self.store
     }
 
+    /// Retrieves the current value [`Val`] that the Global has.
     pub fn get(&self) -> Val {
         unsafe {
             let definition = &mut *self.exported.definition;
@@ -73,6 +84,13 @@ impl Global {
         }
     }
 
+    /// Sets a custom value [`Val`] to the runtime Global.
+    ///
+    /// # Errors
+    ///
+    /// This function will error if:
+    /// * The global is not mutable
+    /// * The type of the `Val` doesn't matches the Global type.
     pub fn set(&self, val: Val) -> Result<(), RuntimeError> {
         if self.ty().mutability != Mutability::Var {
             return Err(RuntimeError::new(

lib/api/src/externals/memory.rs

@@ -7,6 +7,17 @@ use std::sync::Arc;
 use wasm_common::{Pages, ValueType};
 use wasmer_vm::{Export, ExportMemory, Memory as RuntimeMemory, MemoryError};
 
+/// A WebAssembly `memory`.
+///
+/// A memory instance is the runtime representation of a linear memory.
+/// It holds a vector of bytes and an optional maximum size.
+///
+/// The length of the vector always is a multiple of the WebAssembly
+/// page size, which is defined to be the constant 65536 – abbreviated 64Ki.
+/// Like in a memory type, the maximum size in a memory instance is
+/// given in units of this page size.
+///
+/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#memory-instances
 #[derive(Clone)]
 pub struct Memory {
     store: Store,
@@ -14,6 +25,9 @@ pub struct Memory {
 }
 
 impl Memory {
+    /// Creates a new host `Memory` from the provided [`MemoryType`].
+    ///
+    /// This function will construct the `Memory` using the store [`Tunables`].
     pub fn new(store: &Store, ty: MemoryType) -> Result<Memory, MemoryError> {
         let tunables = store.tunables();
         let style = tunables.memory_style(&ty);
@@ -25,10 +39,12 @@ impl Memory {
         })
     }
 
+    /// Returns the underlying [`MemoryType`] corresponding to this runtime `Memory`.
     pub fn ty(&self) -> &MemoryType {
         self.memory.ty()
     }
 
+    /// Returns the [`Store`] that owns this `Memory`.
     pub fn store(&self) -> &Store {
         &self.store
     }
@@ -55,22 +71,31 @@ impl Memory {
         slice::from_raw_parts_mut(def.base, def.current_length)
     }
 
+    /// Returns the pointer to the `Memory`.
     pub fn data_ptr(&self) -> *mut u8 {
         let definition = self.memory.vmmemory();
         let def = unsafe { definition.as_ref() };
         def.base
     }
 
+    /// Returns the size (in bytes) of the `Memory`.
     pub fn data_size(&self) -> usize {
         let definition = self.memory.vmmemory();
         let def = unsafe { definition.as_ref() };
         def.current_length
     }
 
+    /// Returns the size (in [`Pages`]) of the `Memory`.
     pub fn size(&self) -> Pages {
         self.memory.size()
     }
 
+    /// Grow memory by the specified amount of WebAssembly [`Pages`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if memory can't be grown by the specified amount
+    /// of pages.
     pub fn grow<IntoPages>(&self, delta: IntoPages) -> Result<Pages, MemoryError>
     where
         IntoPages: Into<Pages>,

lib/api/src/externals/mod.rs

@@ -15,15 +15,24 @@ use crate::store::{Store, StoreObject};
 use crate::ExternType;
 use wasmer_vm::Export;
 
+/// An external value 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
 #[derive(Clone)]
 pub enum Extern {
+    /// A external [`Function`]
     Function(Function),
+    /// A external [`Global`]
     Global(Global),
+    /// A external [`Table`]
     Table(Table),
+    /// A external [`Memory`]
     Memory(Memory),
 }
 
 impl Extern {
+    /// Return the undelying type of the inner `Extern`.
     pub fn ty(&self) -> ExternType {
         match self {
             Extern::Function(ft) => ExternType::Function(ft.ty().clone()),

lib/api/src/externals/table.rs

@@ -12,6 +12,8 @@ use wasmer_vm::{Export, ExportTable, Table as RuntimeTable, VMCallerCheckedAnyfu
 ///
 /// 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
 #[derive(Clone)]
 pub struct Table {
     store: Store,
@@ -30,6 +32,8 @@ impl Table {
     /// Creates a new `Table` with the provided [`TableType`] definition.
     ///
     /// All the elements in the table will be set to the `init` value.
+    ///
+    /// This function will construct the `Table` using the store [`Tunables`].
     pub fn new(store: &Store, ty: TableType, init: Val) -> Result<Table, RuntimeError> {
         let item = init.into_checked_anyfunc(store)?;
         let tunables = store.tunables();
@@ -54,6 +58,7 @@ impl Table {
         self.table.ty()
     }
 
+    /// Returns the [`Store`] that owns this `Table`.
     pub fn store(&self) -> &Store {
         &self.store
     }

lib/api/src/instance.rs

@@ -12,6 +12,8 @@ use wasmer_vm::InstanceHandle;
 /// Instance objects contain all the exported WebAssembly
 /// functions, memories, tables and globals that allow
 /// interacting with WebAssembly.
+///
+/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#module-instances
 #[derive(Clone)]
 pub struct Instance {
     handle: InstanceHandle,
@@ -94,6 +96,7 @@ impl Instance {
         &self.module
     }
 
+    /// Returns the [`Store`] that owns this `Instance`.
     pub fn store(&self) -> &Store {
         self.module.store()
     }

lib/api/src/lib.rs

@@ -1,5 +1,25 @@
 //! Wasmer API
-#![deny(intra_doc_link_resolution_failure)]
+#![deny(
+    missing_docs,
+    trivial_numeric_casts,
+    unused_extern_crates,
+    intra_doc_link_resolution_failure
+)]
+#![warn(unused_import_braces)]
+#![cfg_attr(feature = "cargo-clippy", allow(clippy::new_without_default))]
+#![cfg_attr(
+    feature = "cargo-clippy",
+    warn(
+        clippy::float_arithmetic,
+        clippy::mut_mut,
+        clippy::nonminimal_bool,
+        clippy::option_map_unwrap_or,
+        clippy::option_map_unwrap_or_else,
+        clippy::print_stdout,
+        clippy::unicode_not_nfc,
+        clippy::use_self
+    )
+)]
 
 mod exports;
 mod externals;

lib/api/src/module.rs

@@ -108,6 +108,7 @@ impl Module {
         Module::from_binary(store, bytes.as_ref())
     }
 
+    /// Creates a new WebAssembly module from a file path.
     pub fn from_file(store: &Store, file: impl AsRef<Path>) -> Result<Module, IoCompileError> {
         let file_ref = file.as_ref();
         let canonical = file_ref.canonicalize()?;
@@ -120,7 +121,7 @@ impl Module {
         Ok(module)
     }
 
-    ///  Creates a new WebAssembly module from a binary.
+    /// Creates a new WebAssembly module from a binary.
     ///
     /// Opposed to [`Module::new`], this function is not compatible with
     /// the WebAssembly text format (if the "wat" feature is enabled for
@@ -394,6 +395,7 @@ impl Module {
         self.artifact.module_ref().custom_sections(name)
     }
 
+    /// Returns the [`Store`] that owns this `Instance`.
     pub fn store(&self) -> &Store {
         &self.store
     }

lib/api/src/native.rs

@@ -20,6 +20,8 @@ use wasmer_vm::{
     ExportFunction, VMContext, VMDynamicFunctionContext, VMFunctionBody, VMFunctionKind,
 };
 
+/// A WebAssembly function that can be called natively
+/// (using the Native ABI).
 pub struct NativeFunc<'a, Args = (), Rets = ()> {
     definition: FunctionDefinition,
     store: Store,

lib/api/src/store.rs

@@ -6,11 +6,16 @@ use wasmer_engine::Tunables as BaseTunables;
 use std::sync::Arc;
 use wasmer_engine::Engine;
 
-/// The store is what holds the directives to the `wasmer` crate, and
+/// The store represents all global state that can be manipulated by
-/// siblings, to act as expected. It holds the engine (that is
+/// WebAssembly programs. It consists of the runtime representation
-/// —amongst many things— used to compile the Wasm bytes into a valid
+/// of all instances of functions, tables, memories, and globals that
-/// module artifact), in addition to the tunables (that is used to
+/// have been allocated during the life time of the abstract machine.
-/// create the memories, tables and globals).
+///
+/// The `Store` holds the engine (that is —amongst many things— used to compile
+/// 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
 #[derive(Clone)]
 pub struct Store {
     engine: Arc<dyn Engine + Send + Sync>,
@@ -18,7 +23,7 @@ pub struct Store {
 }
 
 impl Store {
-    /// Creates a new `Store` with a specific `Engine`.
+    /// Creates a new `Store` with a specific [`Engine`].
     pub fn new<E>(engine: &E) -> Self
     where
         E: Engine + ?Sized,
@@ -29,8 +34,7 @@ impl Store {
         }
     }
 
-    /// Creates a new `Store` with a specific `Engine` and a specific
+    /// Creates a new `Store` with a specific [`Engine`] and [`Tunables`].
-    /// `Tunables`.
     pub fn new_with_tunables<E>(
         engine: &E,
         tunables: impl BaseTunables + Send + Sync + 'static,
@@ -44,12 +48,12 @@ impl Store {
         }
     }
 
-    /// Returns the tunables.
+    /// Returns the [`Tunables`].
     pub fn tunables(&self) -> &dyn BaseTunables {
         self.tunables.as_ref()
     }
 
-    /// Returns the engine.
+    /// Returns the [`Engine`].
     pub fn engine(&self) -> &Arc<dyn Engine + Send + Sync> {
         &self.engine
     }
@@ -115,6 +119,8 @@ impl Default for Store {
     }
 }
 
+/// A trait represinting any object that lives in the `Store`.
 pub trait StoreObject {
+    /// Return true if the object `Store` is the same as the provided `Store`.
     fn comes_from_same_store(&self, store: &Store) -> bool;
 }

lib/api/src/types.rs

@@ -8,6 +8,11 @@ pub use wasm_common::{
     MemoryType, Mutability, TableType, Type as ValType,
 };
 
+/// WebAssembly computations manipulate values of basic value types:
+/// * Integers (32 or 64 bit width)
+/// * Floating-point (32 or 64 bit width)
+///
+/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#values
 pub type Val = Value<Function>;
 
 impl StoreObject for Val {