From 528f468ef22b874185a20bbb58eab69dfeec9e8c Mon Sep 17 00:00:00 2001 From: Sergey Pepyakin Date: Tue, 6 Feb 2018 23:10:58 +0300 Subject: [PATCH] Minor fixes in docs (#38) * Run nightly only if NIGHTLY_TOOLCHAIN is defined * Minor fixes in docs. --- doc.sh | 6 +++++- src/global.rs | 6 ++++-- src/imports.rs | 2 ++ src/memory.rs | 52 ++++++++++++++++++++++++++++++++++++++++++-------- src/module.rs | 8 ++++++++ src/types.rs | 9 ++++----- src/value.rs | 16 +++++++++++----- 7 files changed, 78 insertions(+), 21 deletions(-) diff --git a/doc.sh b/doc.sh index 4c20b7aed25f..514806045f28 100755 --- a/doc.sh +++ b/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. diff --git a/src/global.rs b/src/global.rs index 697b7340ce69..aec71eda25e5 100644 --- a/src/global.rs +++ b/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, @@ -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 } diff --git a/src/imports.rs b/src/imports.rs index 7c93b36a61e3..5907cefdb474 100644 --- a/src/imports.rs +++ b/src/imports.rs @@ -127,6 +127,8 @@ impl<'a> ImportsBuilder<'a> { } /// Register an resolver by a name. + /// + /// Mutable borrowed version. pub fn push_resolver>(&mut self, name: N, resolver: &'a ModuleImportResolver) { self.modules.insert(name.into(), resolver); } diff --git a/src/memory.rs b/src/memory.rs index d408f4495419..6efc4385501d 100644 --- a/src/memory.rs +++ b/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 232 = 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) -> Result { 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 { 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) } diff --git a/src/module.rs b/src/module.rs index b7b3ed7cd97c..e900c0e63578 100644 --- a/src/module.rs +++ b/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); diff --git a/src/types.rs b/src/types.rs index b05e63608dd3..f579afde8836 100644 --- a/src/types.rs +++ b/src/types.rs @@ -50,12 +50,9 @@ 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. +/// See [`RuntimeValue`] for details. /// +/// [`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 } diff --git a/src/value.rs b/src/value.rs index 75035ff2d55a..808210ef3478 100644 --- a/src/value.rs +++ b/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), }