Merge pull request #167 from wasmerio/docs-spec

Added spec docs to app API public objects

lib/api/src/externals/function.rs

@@ -37,7 +37,17 @@ pub enum FunctionDefinition {
     Host(HostFunctionDefinition),
 }
 
-/// A WebAssembly `function`.
+/// A WebAssembly `function` instance.
+///
+/// A function instance is the runtime representation of a function.
+/// It effectively is a closure of the original function (defined in either
+/// the host or the WebAssembly module) 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 +56,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 +87,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 +125,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 +160,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 +197,12 @@ impl Function {
         }
     }
 
-    /// Returns the underlying type of this function.
+    /// Returns the [`FunctionType`] of the `Function`.
     pub fn ty(&self) -> &FunctionType {
         &self.exported.signature
     }
 
+    /// Returns the [`Store`] where the `Function` belongs.
     pub fn store(&self) -> &Store {
         &self.store
     }

lib/api/src/externals/global.rs

@@ -8,19 +8,27 @@ use crate::RuntimeError;
 use std::fmt;
 use wasmer_vm::{Export, ExportGlobal, VMGlobalDefinition};
 
+/// A WebAssembly `global` instance.
+///
+/// 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
 #[derive(Clone)]
 pub struct Global {
     store: Store,
     exported: ExportGlobal,
 }
 
 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 [`GlobalType`] of the `Global`.
     pub fn ty(&self) -> &GlobalType {
         &self.exported.global
     }
 
+    /// Returns the [`Store`] where the `Global` belongs.
     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,13 +7,30 @@ use std::sync::Arc;
 use wasm_common::{Pages, ValueType};
 use wasmer_vm::{Export, ExportMemory, Memory as RuntimeMemory, MemoryError};
 
+/// A WebAssembly `memory` instance.
+///
+/// A memory instance is the runtime representation of a linear memory.
+/// It consists of 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.
+///
+/// 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
 #[derive(Clone)]
 pub struct Memory {
     store: Store,
     memory: Arc<dyn RuntimeMemory>,
 }
 
 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 +42,12 @@ impl Memory {
         })
     }
 
+    /// Returns the [`MemoryType`] of the `Memory`.
     pub fn ty(&self) -> &MemoryType {
         self.memory.ty()
     }
 
+    /// Returns the [`Store`] where the `Memory` belongs.
     pub fn store(&self) -> &Store {
         &self.store
     }
@@ -55,22 +74,31 @@ impl Memory {
         slice::from_raw_parts_mut(def.base, def.current_length)
     }
 
+    /// Returns the pointer to the raw bytes of 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 `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
 #[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

@@ -7,11 +7,15 @@ use crate::TableType;
 use std::sync::Arc;
 use wasmer_vm::{Export, ExportTable, Table as RuntimeTable, VMCallerCheckedAnyfunc};
 
+/// A WebAssembly `table` instance.
+///
 /// The `Table` struct is an array-like structure representing a WebAssembly Table,
 /// which stores function references.
 ///
 /// 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 +34,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();
@@ -49,11 +55,12 @@ impl Table {
         })
     }
 
-    /// Gets the underlying [`TableType`].
+    /// Returns the [`TableType`] of the `Table`.
     pub fn ty(&self) -> &TableType {
         self.table.ty()
     }
 
+    /// Returns the [`Store`] where the `Table` belongs.
     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`] where the `Instance` belongs.
     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`] where the `Instance` belongs.
     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,