Merge pull request #11 from pepyakin/docs-1

First iteration on documentation.

src/func.rs

@@ -10,6 +10,12 @@ use module::ModuleInstance;
 use common::stack::StackWithLimit;
 use common::{DEFAULT_FRAME_STACK_LIMIT, DEFAULT_VALUE_STACK_LIMIT};
 
+/// Reference to a [`FuncInstance`].
+///
+/// This reference has a reference-counting semantics.
+///
+/// [`FuncInstance`]: struct.FuncInstance.html
+///
 #[derive(Clone, Debug)]
 pub struct FuncRef(Rc<FuncInstance>);
 
@@ -20,6 +26,21 @@ impl ::std::ops::Deref for FuncRef {
 	}
 }
 
+/// Runtime representation of a function.
+///
+/// Functions are the unit of orgianization of code in WebAssembly. Each function takes a sequence of values
+/// as parameters and either optionally return a value or trap.
+/// Functions can call other function (including itself, i.e recursively) and imported functions
+/// (i.e defined in another module).
+///
+/// Functions can be defined either:
+///
+/// - by a wasm module,
+/// - by the host environment and passed to a wasm module as an import.
+///   See more in [`Externals`].
+///
+/// [`Externals`]: trait.Externals.html
+///
 pub struct FuncInstance(FuncInstanceInternal);
 
 #[derive(Clone)]

src/global.rs

@@ -5,6 +5,12 @@ use Error;
 use types::ValueType;
 use parity_wasm::elements::{ValueType as EValueType};
 
+/// Reference to a [`GlobalInstance`].
+///
+/// This reference has a reference-counting semantics.
+///
+/// [`GlobalInstance`]: struct.GlobalInstance.html
+///
 #[derive(Clone, Debug)]
 pub struct GlobalRef(Rc<GlobalInstance>);
 
@@ -15,6 +21,15 @@ impl ::std::ops::Deref for GlobalRef {
 	}
 }
 
+/// Runtime representation of a global variable (or `global` for short).
+///
+/// Global contains a value of a specified type and flag which specifies whether this
+/// global are mutable or immutable. Neither type of the value nor immutability can't be changed
+/// after creation.
+///
+/// Attempt to change value of immutable global or to change type of
+/// the value (e.g. assign I32 value to a global that was created with I64 type) will lead to an error.
+///
 #[derive(Debug)]
 pub struct GlobalInstance {
 	val: Cell<RuntimeValue>,

src/host.rs

@@ -2,7 +2,7 @@ use std::any::TypeId;
 use value::{RuntimeValue, TryInto};
 use Error;
 
-/// Safe wrapper for list of arguments
+/// Safe wrapper for list of arguments.
 #[derive(Debug)]
 pub struct RuntimeArgs<'a>(&'a [RuntimeValue]);
 

src/memory.rs

@@ -13,6 +13,12 @@ pub const LINEAR_MEMORY_PAGE_SIZE: u32 = 65536;
 /// Maximal number of pages.
 const LINEAR_MEMORY_MAX_PAGES: u32 = 65536;
 
+/// Reference to a [`MemoryInstance`].
+///
+/// This reference has a reference-counting semantics.
+///
+/// [`MemoryInstance`]: struct.MemoryInstance.html
+///
 #[derive(Clone, Debug)]
 pub struct MemoryRef(Rc<MemoryInstance>);
 
@@ -23,7 +29,15 @@ impl ::std::ops::Deref for MemoryRef {
 	}
 }
 
-/// Linear memory instance.
+/// Runtime representation of a linear memory (or `memory` for short).
+///
+/// A memory is a contiguous, mutable array of raw bytes. Wasm code can load and store values
+/// from/to a linear memory at any byte address.
+/// A trap occurs if an access is not within the bounds of the current memory size.
+///
+/// A memory is created with an initial size but can be grown dynamically.
+/// The growth can be limited by specifying maximum size.
+/// The size of a memory is always a integer multiple of a page size - 64KiB.
 pub struct MemoryInstance {
 	/// Memofy limits.
 	limits: ResizableLimits,

src/table.rs

@@ -7,6 +7,12 @@ use Error;
 use func::FuncRef;
 use module::check_limits;
 
+/// Reference to a [`TableInstance`].
+///
+/// This reference has a reference-counting semantics.
+///
+/// [`TableInstance`]: struct.TableInstance.html
+///
 #[derive(Clone, Debug)]
 pub struct TableRef(Rc<TableInstance>);
 
@@ -17,7 +23,19 @@ impl ::std::ops::Deref for TableRef {
 	}
 }
 
-/// Table instance.
+/// Runtime representation of a table.
+///
+/// A table is a array of untyped functions. It allows wasm code to call functions
+/// indirectly through a dynamic index into a table. For example, this allows emulating function
+/// pointers by way of table indices.
+///
+/// Table is created with an initial size but can be grown dynamically via [`grow`] method.
+/// Growth can be limited by an optional maximum size.
+///
+/// In future, a table might be extended to be able to hold not only functions but different types.
+///
+/// [`grow`]: #method.grow
+///
 pub struct TableInstance {
 	/// Table limits.
 	limits: ResizableLimits,

src/types.rs

@@ -1,7 +1,14 @@
 use parity_wasm::elements::{
 	FunctionType, ValueType as EValueType, GlobalType, TableType, MemoryType};
 
-#[derive(Debug, Clone, PartialEq)]
+/// Signature of a function.
+///
+/// Signature of a function consists of zero or more parameter [types][type] and zero or one return [type].
+///
+/// Two signatures are considered equal if they have equal list of parameters and equal return types.
+///
+/// [type]: enum.ValueType.html
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Signature {
 	params: Vec<ValueType>,
 	return_type: Option<ValueType>,
@@ -31,6 +38,14 @@ impl Signature {
 	}
 }
 
+/// Type of a value.
+///
+/// Wasm code manipulate values of the four basic value types:
+/// integers and floating-point (IEEE 754-2008) data of 32 or 64 bit width each, respectively.
+///
+/// There is no distinction between signed and unsigned integer types. Instead, integers are
+/// interpreted by respective operations as either unsigned or signed in two’s complement representation.
+///
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum ValueType {
 	I32,