more docs and warnings

src/graph.rs

@@ -1,5 +1,7 @@
 //! Wasm binary graph format
 
+#![warn(missing_docs)]
+
 use parity_wasm::elements;
 use super::ref_list::{RefList, EntryRef};
 use std::vec::Vec;
@@ -168,15 +170,25 @@ pub struct Export {
 /// Module
 #[derive(Debug, Default)]
 pub struct Module {
+	/// Refence-tracking list of types.
 	pub types: RefList<elements::Type>,
+	/// Refence-tracking list of funcs.
 	pub funcs: RefList<Func>,
+	/// Refence-tracking list of memory instances.
 	pub memory: RefList<Memory>,
+	/// Refence-tracking list of table instances.
 	pub tables: RefList<Table>,
+	/// Refence-tracking list of globals.
 	pub globals: RefList<Global>,
+	/// Reference to start function.
 	pub start: Option<EntryRef<Func>>,
+	/// References to exported objects.
 	pub exports: Vec<Export>,
+	/// List of element segments.
 	pub elements: Vec<ElementSegment>,
+	/// List of data segments.
 	pub data: Vec<DataSegment>,
+	/// Other module functions that are not decoded or processed.
 	pub other: BTreeMap<usize, elements::Section>,
 }
 
@@ -210,6 +222,7 @@ impl Module {
 		}).collect()
 	}
 
+	/// Initialize module from parity-wasm `Module`.
 	pub fn from_elements(module: &elements::Module) -> Self {
 
 		let mut idx = 0;
@@ -721,10 +734,12 @@ fn custom_round(
 	}
 }
 
+/// New module from parity-wasm `Module`
 pub fn parse(wasm: &[u8]) -> Module {
 	Module::from_elements(&::parity_wasm::deserialize_buffer(wasm).expect("failed to parse wasm"))
 }
 
+/// Generate parity-wasm `Module`
 pub fn generate(f: &Module) -> Vec<u8> {
 	let pm = f.generate();
 	::parity_wasm::serialize(pm).expect("failed to generate wasm")

src/ref_list.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 
 use std::rc::Rc;
 use std::cell::RefCell;
@@ -16,6 +17,7 @@ impl From<usize> for EntryOrigin {
 	}
 }
 
+/// Reference counting, link-handling object.
 #[derive(Debug)]
 pub struct Entry<T> {
 	val: T,
@@ -23,13 +25,15 @@ pub struct Entry<T> {
 }
 
 impl<T> Entry<T> {
-	fn new(val: T, index: usize) -> Entry<T> {
+	/// New entity.
+	pub fn new(val: T, index: usize) -> Entry<T> {
 		Entry {
 			val: val,
 			index: EntryOrigin::Index(index),
 		}
 	}
 
+	/// Index of the element within the reference list.
 	pub fn order(&self) -> Option<usize> {
 		match self.index {
 			EntryOrigin::Detached => None,
@@ -52,6 +56,8 @@ impl<T> ::std::ops::DerefMut for Entry<T> {
 	}
 }
 
+/// Reference to the entry in the rerence list.
+#[derive(Debug)]
 pub struct EntryRef<T>(Rc<RefCell<Entry<T>>>);
 
 impl<T> Clone for EntryRef<T> {
@@ -67,18 +73,24 @@ impl<T> From<Entry<T>> for EntryRef<T> {
 }
 
 impl<T> EntryRef<T> {
+	/// Read the reference data.
 	pub fn read(&self) -> ::std::cell::Ref<Entry<T>> {
 		self.0.borrow()
 	}
 
+	/// Try to modify internal content of the referenced object.
+	///
+	/// May panic if it is already borrowed.
 	pub fn write(&self) -> ::std::cell::RefMut<Entry<T>> {
 		self.0.borrow_mut()
 	}
 
+	/// Index of the element within the reference list.
 	pub fn order(&self) -> Option<usize> {
 		self.0.borrow().order()
 	}
 
+	/// Number of active links to this entity.
 	pub fn link_count(&self) -> usize {
 		Rc::strong_count(&self.0) - 1
 	}