Minor fixes in docs (#38)

* Run nightly only if NIGHTLY_TOOLCHAIN is defined

* Minor fixes in docs.

doc.sh

@@ -4,7 +4,11 @@ set -eux
 
 cd $(dirname $0)
 
-rustup run $NIGHTLY_TOOLCHAIN cargo doc
+if [ -s NIGHTLY_TOOLCHAIN ]; then
+	rustup run $NIGHTLY_TOOLCHAIN cargo doc
+else
+	cargo doc
+fi;
 
 # cargo-deadlinks will check any links in docs generated by `cargo doc`.
 # This is useful as rustdoc uses raw links which are error prone.

src/global.rs

@@ -27,8 +27,10 @@ impl ::std::ops::Deref for GlobalRef {
 /// 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.
+/// the value (e.g. assign [`I32`] value to a global that was created with [`I64`] type) will lead to an error.
 ///
+/// [`I32`]: enum.RuntimeValue.html#variant.I32
+/// [`I64`]: enum.RuntimeValue.html#variant.I64
 #[derive(Debug)]
 pub struct GlobalInstance {
 	val: Cell<RuntimeValue>,
@@ -71,7 +73,7 @@ impl GlobalInstance {
 
 	/// Returns if this global variable is mutable.
 	///
-	/// Imported and/or exported globals are always immutable.
+	/// Note: Imported and/or exported globals are always immutable.
 	pub fn is_mutable(&self) -> bool {
 		self.mutable
 	}

src/imports.rs

@@ -127,6 +127,8 @@ impl<'a> ImportsBuilder<'a> {
 	}
 
 	/// Register an resolver by a name.
+	///
+	/// Mutable borrowed version.
 	pub fn push_resolver<N: Into<String>>(&mut self, name: N, resolver: &'a ModuleImportResolver) {
 		self.modules.insert(name.into(), resolver);
 	}

src/memory.rs

@@ -42,9 +42,11 @@ impl ::std::ops::Deref for MemoryRef {
 ///
 /// 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.
+/// The size of a memory is always a integer multiple of a [page size][`LINEAR_MEMORY_PAGE_SIZE`] - 64KiB.
 ///
 /// At the moment, wasm doesn't provide any way to shrink the memory.
+///
+/// [`LINEAR_MEMORY_PAGE_SIZE`]: constant.LINEAR_MEMORY_PAGE_SIZE.html
 pub struct MemoryInstance {
 	/// Memofy limits.
 	limits: ResizableLimits,
@@ -92,7 +94,7 @@ impl MemoryInstance {
 	///
 	/// The memory allocated with initial number of pages specified by `initial_pages`.
 	/// Minimal possible value for `initial_pages` is 0 and maximum possible is `65536`.
-	/// (Since maximum addressible memory is 4GiB = 65536 * 64KiB).
+	/// (Since maximum addressible memory is 2<sup>32</sup> = 4GiB = 65536 * [64KiB][`LINEAR_MEMORY_PAGE_SIZE`]).
 	///
 	/// It is possible to limit maximum number of pages this memory instance can have by specifying
 	/// `maximum_page`. If not specified, this memory instance would be able to allocate up to 4GiB.
@@ -101,7 +103,12 @@ impl MemoryInstance {
 	///
 	/// # Errors
 	///
-	/// Returns `Err` if `initial_pages` is greater than `maximum_pages`.
+	/// Returns `Err` if:
+	///
+	/// - `initial_pages` is greater than `maximum_pages`
+	/// - either `initial_pages` or `maximum_pages` is greater than `65536`.
+	///
+	/// [`LINEAR_MEMORY_PAGE_SIZE`]: constant.LINEAR_MEMORY_PAGE_SIZE.html
 	pub fn alloc(initial_pages: u32, maximum_pages: Option<u32>) -> Result<MemoryRef, Error> {
 		let memory = MemoryInstance::new(ResizableLimits::new(initial_pages, maximum_pages))?;
 		Ok(MemoryRef(Rc::new(memory)))
@@ -165,6 +172,10 @@ impl MemoryInstance {
 	}
 
 	/// Copy data from given offset in the memory into `target` slice.
+	///
+	/// # Errors
+	///
+	/// Returns `Err` if the specified region is out of bounds.
 	pub fn get_into(&self, offset: u32, target: &mut [u8]) -> Result<(), Error> {
 		let buffer = self.buffer.borrow();
 		let region = self.checked_region(&buffer, offset as usize, target.len())?;
@@ -189,7 +200,7 @@ impl MemoryInstance {
 	///
 	/// # Errors
 	///
-	/// Returns `Err` if tried to allocate more memory than permited by limit.
+	/// Returns `Err` if attempted to allocate more memory than permited by the limit.
 	pub fn grow(&self, pages: u32) -> Result<u32, Error> {
 		let mut buffer = self.buffer.borrow_mut();
 		let old_size = buffer.len() as u32;
@@ -225,7 +236,13 @@ impl MemoryInstance {
 		})
 	}
 
-	/// Copy memory region. Semantically equivalent to `memmove`.
+	/// Copy contents of one memory region to another.
+	///
+	/// Semantically equivalent to `memmove`.
+	///
+	/// # Errors
+	///
+	/// Returns `Err` if either of specified regions is out of bounds.
 	pub fn copy(&self, src_offset: usize, dst_offset: usize, len: usize) -> Result<(), Error> {
 		let buffer = self.buffer.borrow_mut();
 
@@ -241,8 +258,17 @@ impl MemoryInstance {
 		Ok(())
 	}
 
-	/// Copy memory region, non-overlapping version. Semantically equivalent to `memcpy`,
+	/// Copy contents of one memory region to another (non-overlapping version).
+	///
+	/// Semantically equivalent to `memcpy`.
 	/// but returns Error if source overlaping with destination.
+	///
+	/// # Errors
+	///
+	/// Returns `Err` if:
+	///
+	/// - either of specified regions is out of bounds,
+	/// - these regions overlaps.
 	pub fn copy_nonoverlapping(&self, src_offset: usize, dst_offset: usize, len: usize) -> Result<(), Error> {
 		let buffer = self.buffer.borrow_mut();
 
@@ -262,7 +288,13 @@ impl MemoryInstance {
 		Ok(())
 	}
 
-	/// Clear memory region with a specified value. Semantically equivalent to `memset`.
+	/// Fill memory region with a specified value.
+	///
+	/// Semantically equivalent to `memset`.
+	///
+	/// # Errors
+	///
+	/// Returns `Err` if the specified region is out of bounds.
 	pub fn clear(&self, offset: usize, new_val: u8, len: usize) -> Result<(), Error> {
 		let mut buffer = self.buffer.borrow_mut();
 
@@ -271,7 +303,11 @@ impl MemoryInstance {
 		Ok(())
 	}
 
-	/// Zero memory region
+	/// Fill specified memory region with zeroes.
+	///
+	/// # Errors
+	///
+	/// Returns `Err` if the specified region is out of bounds.
 	pub fn zero(&self, offset: usize, len: usize) -> Result<(), Error> {
 		self.clear(offset, 0, len)
 	}

src/module.rs

@@ -19,6 +19,14 @@ use types::{GlobalDescriptor, TableDescriptor, MemoryDescriptor};
 ///
 /// This reference has a reference-counting semantics.
 ///
+/// All [`ModuleInstance`] have strong references to it's components (i.e.
+/// globals, memories, funcs, tables), however, this components have
+/// weak references to it's containing module. This might be a problem
+/// at execution time.
+///
+/// So if have to make sure that all modules which might be needed at execution time
+/// should be retained.
+///
 /// [`ModuleInstance`]: struct.ModuleInstance.html
 #[derive(Clone, Debug)]
 pub struct ModuleRef(pub(crate) Rc<ModuleInstance>);

src/types.rs

@@ -50,12 +50,9 @@ impl Signature {
 
 /// Type of a value.
 ///
-/// Wasm code manipulate values of the four basic value types:
+/// See [`RuntimeValue`] for details.
-/// 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.
 ///
+/// [`RuntimeValue`]: enum.RuntimeValue.html
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum ValueType {
 	/// 32-bit signed or unsigned integer.
@@ -108,6 +105,8 @@ impl GlobalDescriptor {
 	}
 
 	/// Returns [`ValueType`] of the requested global.
+	///
+	/// [`ValueType`]: enum.ValueType.html
 	pub fn value_type(&self) -> ValueType {
 		self.value_type
 	}

src/value.rs

@@ -12,16 +12,22 @@ pub enum Error {
 	InvalidLittleEndianBuffer,
 }
 
-/// Runtime value.
+/// Runtime representation 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)]
 pub enum RuntimeValue {
-	/// 32b-length signed/unsigned int.
+	/// Value of 32-bit signed or unsigned integer.
 	I32(i32),
-	/// 64b-length signed/unsigned int.
+	/// Value of 64-bit signed or unsigned integer.
 	I64(i64),
-	/// 32b-length float.
+	/// Value of 32-bit IEEE 754-2008 floating point number.
 	F32(f32),
-	/// 64b-length float.
+	/// Value of 64-bit IEEE 754-2008 floating point number.
 	F64(f64),
 }