Documentation.

substrate/native-runtime/support/src/lib.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Support functions.
+
 #[macro_use]
 extern crate environmental;
 extern crate polkadot_state_machine;

substrate/wasm-runtime/polkadot/src/codec/endiansensitive.rs

@@ -1,3 +1,22 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Endian manager.
+
+/// Trait to allow conversion to a know endian representation when sensitive.
 pub trait EndianSensitive: Sized {
 	fn to_le(self) -> Self { self }
 	fn to_be(self) -> Self { self }

substrate/wasm-runtime/polkadot/src/codec/joiner.rs

@@ -1,6 +1,25 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Vec<u8> serialiser.
+
 use runtime_support::Vec;
 use slicable::Slicable;
 
+/// Trait to allow itself to be serialised into a `Vec<u8>`
 pub trait Joiner {
 	fn join<T: Slicable + Sized>(self, value: &T) -> Self;
 }

substrate/wasm-runtime/polkadot/src/codec/keyedvec.rs

@@ -1,6 +1,25 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Serialiser and prepender.
+
 use runtime_support::Vec;
 use slicable::Slicable;
 
+/// Trait to allow itselg to be serialised and prepended by a given slice.
 pub trait KeyedVec {
 	fn to_keyed_vec(&self, prepend_key: &[u8]) -> Vec<u8>;
 }

substrate/wasm-runtime/polkadot/src/codec/mod.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Codec utils.
+
 pub mod endiansensitive;
 pub mod streamreader;
 pub mod joiner;

substrate/wasm-runtime/polkadot/src/codec/slicable.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Serialisation.
+
 use runtime_support::{Vec, size_of, transmute, uninitialized, slice};
 use joiner::Joiner;
 use endiansensitive::EndianSensitive;
@@ -22,6 +40,7 @@ pub trait Slicable: Sized {
 	fn size_of(_value: &[u8]) -> Option<usize>;
 }
 
+/// Trait to mark that a type is not trivially (essentially "in place") serialisable.
 pub trait NonTrivialSlicable: Slicable {}
 
 impl<T: EndianSensitive> Slicable for T {

substrate/wasm-runtime/polkadot/src/codec/streamreader.rs

@@ -1,17 +1,39 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Deserialiser.
+
 use slicable::Slicable;
 
+/// Simple deserialiser.
 pub struct StreamReader<'a> {
 	data: &'a[u8],
 	offset: usize,
 }
 
 impl<'a> StreamReader<'a> {
+	/// Create a new deserialiser based on the `data`.
 	pub fn new(data: &'a[u8]) -> Self {
 		StreamReader {
 			data: data,
 			offset: 0,
 		}
 	}
+
+	/// Deserialise a single item from the data stream.
 	pub fn read<T: Slicable>(&mut self) -> Option<T> {
 		let size = T::size_of(&self.data[self.offset..])?;
 		let new_offset = self.offset + size;

substrate/wasm-runtime/polkadot/src/lib.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! The Polkadot runtime. This can be compiled with #[no_std], ready for Wasm.
+
 #![cfg_attr(feature = "without-std", no_std)]
 #![cfg_attr(feature = "strict", deny(warnings))]
 
@@ -20,11 +38,14 @@ use runtime_support::Vec;
 use slicable::Slicable;
 use primitives::{Block, UncheckedTransaction};
 
+/// Execute a block, with `input` being the canonical serialisation of the block. Returns the
+/// empty vector.
 pub fn execute_block(input: Vec<u8>) -> Vec<u8> {
 	runtime::system::execute_block(Block::from_slice(&input).unwrap());
 	Vec::new()
 }
 
+/// Execute a given, serialised, transaction. Returns the empty vector.
 pub fn execute_transaction(input: Vec<u8>) -> Vec<u8> {
 	runtime::system::execute_transaction(&UncheckedTransaction::from_slice(&input).unwrap());
 	Vec::new()

substrate/wasm-runtime/polkadot/src/runtime/consensus.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Conensus module for runtime; manages the authority set ready for the native code.
+
 use runtime_support::Vec;
 use storable::StorageVec;
 use primitives::SessionKey;

substrate/wasm-runtime/polkadot/src/runtime/mod.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! The Polkadot runtime.
+
 #[allow(unused)]
 pub mod system;
 #[allow(unused)]

substrate/wasm-runtime/polkadot/src/runtime/session.rs

@@ -1,3 +1,22 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Session manager: is told the validators and allows them to manage their session keys for the
+//! consensus module.
+
 use runtime_support::Vec;
 use keyedvec::KeyedVec;
 use storable::{kill, Storable, StorageVec};

substrate/wasm-runtime/polkadot/src/runtime/staking.rs

@@ -1,10 +1,32 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Staking manager: Handles balances and periodically determines the best set of validators.
+
 use runtime_support::Vec;
 use keyedvec::KeyedVec;
 use storable::{Storable, StorageVec};
-use primitives::{BlockNumber, Balance, AccountID};
+use primitives::{BlockNumber, AccountID};
 use runtime::{system, session};
 
-type Liquidity = u64;
+/// The balance of an account.
+pub type Balance = u64;
+
+/// The amount of bonding period left in an account. Measured in eras.
+pub type Bondage = u64;
 
 struct IntentionStorageVec {}
 impl StorageVec for IntentionStorageVec {
@@ -48,45 +70,13 @@ pub fn last_era_length_change() -> BlockNumber {
 	Storable::lookup_default(b"sta:lec")
 }
 
-/// The era has changed - enact new staking set.
-///
-/// NOTE: This always happens on a session change.
-fn new_era() {
-	// Increment current era.
-	(current_era() + 1).store(b"sta:era");
-
-	// Enact era length change.
-	let next_spe: u64 = Storable::lookup_default(b"sta:nse");
-	if next_spe > 0 && next_spe != sessions_per_era() {
-		next_spe.store(b"sta:spe");
-		system::block_number().store(b"sta:lec");
-	}
-
-	// TODO: evaluate desired staking amounts and nominations and optimise to find the best
-	// combination of validators, then use session::set_validators().
-
-	// for now, this just orders would-be stakers by their balances and chooses the top-most
-	// validator_count() of them.
-	let mut intentions = IntentionStorageVec::items()
-		.into_iter()
-		.map(|v| (balance(&v), v))
-		.collect::<Vec<_>>();
-	intentions.sort_unstable_by(|&(b1, _), &(b2, _)| b2.cmp(&b1));
-	session::set_validators(
-		&intentions.into_iter()
-			.map(|(_, v)| v)
-			.take(validator_count())
-			.collect::<Vec<_>>()
-	);
-}
-
 /// The balance of a given account.
 pub fn balance(who: &AccountID) -> Balance {
 	Storable::lookup_default(&who.to_keyed_vec(b"sta:bal:"))
 }
 
 /// The liquidity-state of a given account.
-pub fn bondage(who: &AccountID) -> Liquidity {
+pub fn bondage(who: &AccountID) -> Bondage {
 	Storable::lookup_default(&who.to_keyed_vec(b"sta:bon:"))
 }
 
@@ -134,6 +124,40 @@ pub fn check_new_era() {
 	}
 }
 
+// PRIVATE
+
+/// The era has changed - enact new staking set.
+///
+/// NOTE: This always happens on a session change.
+fn new_era() {
+	// Increment current era.
+	(current_era() + 1).store(b"sta:era");
+
+	// Enact era length change.
+	let next_spe: u64 = Storable::lookup_default(b"sta:nse");
+	if next_spe > 0 && next_spe != sessions_per_era() {
+		next_spe.store(b"sta:spe");
+		system::block_number().store(b"sta:lec");
+	}
+
+	// TODO: evaluate desired staking amounts and nominations and optimise to find the best
+	// combination of validators, then use session::set_validators().
+
+	// for now, this just orders would-be stakers by their balances and chooses the top-most
+	// validator_count() of them.
+	let mut intentions = IntentionStorageVec::items()
+		.into_iter()
+		.map(|v| (balance(&v), v))
+		.collect::<Vec<_>>();
+	intentions.sort_unstable_by(|&(b1, _), &(b2, _)| b2.cmp(&b1));
+	session::set_validators(
+		&intentions.into_iter()
+			.map(|(_, v)| v)
+			.take(validator_count())
+			.collect::<Vec<_>>()
+	);
+}
+
 /// Set a new era length. Won't kick in until the next era change (at current length).
 fn set_sessions_per_era(new: BlockNumber) {
 	new.store(b"sta:nse");

substrate/wasm-runtime/polkadot/src/runtime/system.rs

@@ -1,3 +1,22 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! System manager: Handles all of the top-level stuff; executing block/transaction, setting code
+//! and depositing logs.
+
 use primitives::{Block, BlockNumber, Hash, UncheckedTransaction, TxOrder, Hashable};
 use runtime_support::{Vec, swap};
 use storable::Storable;

substrate/wasm-runtime/polkadot/src/runtime/timestamp.rs

@@ -1,10 +1,32 @@
-use primitives::Timestamp;
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Timestamp manager: just handles the current timestamp.
+
 use storable::Storable;
 
+/// Representation of a time.
+pub type Timestamp = u64;
+
+/// Get the current time.
 pub fn get() -> Timestamp {
 	Storable::lookup_default(b"tim:val")
 }
 
+/// Set the current time.
 pub fn set(now: Timestamp) {
 	now.store(b"tim:val")
 }

substrate/wasm-runtime/polkadot/src/support/environment.rs

@@ -1,13 +1,36 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Environment API: Allows certain information to be accessed throughout the runtime.
+
 use runtime_support::{Rc, RefCell, transmute, Box};
 use primitives::{BlockNumber, Digest};
 
 #[derive(Default)]
+/// The information that can be accessed globally.
 pub struct Environment {
+	/// The current block number.
 	pub block_number: BlockNumber,
+	/// The current block digest.
 	pub digest: Digest,
+	/// The number of log items in this block that have been accounted for so far.
 	pub next_log_index: usize,
 }
 
+/// Do something with the environment and return its value. Keep the function short.
 pub fn with_env<T, F: FnOnce(&mut Environment) -> T>(f: F) -> T {
 	let e = env();
 	let mut eb = e.borrow_mut();
@@ -15,7 +38,7 @@ pub fn with_env<T, F: FnOnce(&mut Environment) -> T>(f: F) -> T {
 }
 
 #[cfg(not(test))]
-pub fn env() -> Rc<RefCell<Environment>> {
+fn env() -> Rc<RefCell<Environment>> {
 	// Initialize it to a null value
 	static mut SINGLETON: *const Rc<RefCell<Environment>> = 0 as *const Rc<RefCell<Environment>>;
 
@@ -34,7 +57,7 @@ pub fn env() -> Rc<RefCell<Environment>> {
 }
 
 #[cfg(test)]
-pub fn env() -> Rc<RefCell<Environment>> {
+fn env() -> Rc<RefCell<Environment>> {
 	// Initialize it to a null value
 	thread_local!{
 		static SINGLETON: RefCell<*const Rc<RefCell<Environment>>> = RefCell::new(0 as *const Rc<RefCell<Environment>>);

substrate/wasm-runtime/polkadot/src/support/function.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Function data: This describes a function that can be called from an external transaction.
+
 use primitives::AccountID;
 use streamreader::StreamReader;
 use runtime::{staking, session, timestamp};
@@ -14,6 +32,7 @@ pub enum Function {
 }
 
 impl Function {
+	/// Derive `Some` value from a `u8`, or `None` if it's invalid.
 	pub fn from_u8(value: u8) -> Option<Function> {
 		match value {
 			x if x == Function::StakingStake as u8 => Some(Function::StakingStake),

substrate/wasm-runtime/polkadot/src/support/mod.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Support code for the runtime.
+
 pub mod primitives;
 pub mod function;
 pub mod environment;

substrate/wasm-runtime/polkadot/src/support/primitives.rs

@@ -1,3 +1,21 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Primitive types.
+
 use runtime_support::Vec;
 use streamreader::StreamReader;
 use joiner::Joiner;
@@ -13,26 +31,36 @@ pub type AccountID = [u8; 32];
 /// The Ed25519 pub key of an session that belongs to an authority. This is used as what the
 /// external environment/consensus algorithm calls an "authority".
 pub type SessionKey = AccountID;
-pub type Balance = u64;
+/// Indentifier for a chain.
 pub type ChainID = u64;
-pub type Hash = [u8; 32];
+/// Index of a block in the chain.
 pub type BlockNumber = u64;
-pub type Timestamp = u64;
+/// Index of a transaction.
 pub type TxOrder = u64;
+/// A hash of some data.
+pub type Hash = [u8; 32];
 
 #[derive(Clone, Default)]
 #[cfg_attr(test, derive(PartialEq, Debug))]
+/// The digest of a block, useful for light-clients.
 pub struct Digest {
+	/// All logs that have happened in the block.
 	pub logs: Vec<Vec<u8>>,
 }
 
 #[derive(Clone)]
 #[cfg_attr(test, derive(PartialEq, Debug))]
+/// The header for a block.
 pub struct Header {
+	/// The parent block's "hash" (actually the Blake2-256 hash of its serialised header).
 	pub parent_hash: Hash,
+	/// The block's number (how many ancestors does it have?).
 	pub number: BlockNumber,
+	/// The root of the trie that represents this block's final storage map.
 	pub state_root: Hash,
+	/// The root of the trie that represents this block's transactions, indexed by a 32-bit integer.
 	pub transaction_root: Hash,
+	/// The digest for this block.
 	pub digest: Digest,
 }
 
@@ -71,10 +99,15 @@ impl Slicable for Header {
 impl NonTrivialSlicable for Header {}
 
 #[cfg_attr(test, derive(PartialEq, Debug))]
+/// A vetted and verified transaction from the external world.
 pub struct Transaction {
+	/// Who signed it (note this is not a signature).
 	pub signed: AccountID,
+	/// The number of transactions have come before from the same signer.
 	pub nonce: TxOrder,
+	/// The function that should be called.
 	pub function: Function,
+	/// Serialised input data to the function.
 	pub input_data: Vec<u8>,
 }
 
@@ -128,12 +161,16 @@ impl<T: Slicable> Hashable for T {
 
 impl NonTrivialSlicable for Transaction {}
 
+/// A transactions right from the external world. Unchecked.
 pub struct UncheckedTransaction {
+	/// The actual transaction information.
 	pub transaction: Transaction,
+	/// The signature; should be an Ed25519 signature applied to the serialised `transaction` field.
 	pub signature: [u8; 64],
 }
 
 impl UncheckedTransaction {
+	/// Verify the signature.
 	pub fn ed25519_verify(&self) -> bool {
 		let msg = self.transaction.to_vec();
 		ed25519_verify(&self.signature, &msg, &self.transaction.signed)
@@ -183,8 +220,11 @@ impl Slicable for UncheckedTransaction {
 impl NonTrivialSlicable for UncheckedTransaction {}
 
 #[cfg_attr(test, derive(PartialEq, Debug))]
+/// A Polkadot relay chain block.
 pub struct Block {
+	/// The header of the block.
 	pub header: Header,
+	/// All transactions.
 	pub transactions: Vec<UncheckedTransaction>,
 }
 

substrate/wasm-runtime/polkadot/src/support/statichex.rs

@@ -1,6 +1,26 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Interpret a static string of hex as a desired type.
+
 use rustc_hex::FromHex;
 
+/// Trait to allow conversion from a static hex string to an instance.
 pub trait StaticHexConversion: Sized {
+	/// Convert the static str into Self. Use just like `From::from`.
 	fn from_static_hex(hex: &'static str) -> Self;
 }
 
@@ -18,7 +38,10 @@ macro_rules! impl_sizes {
 
 impl_sizes!(1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, 28, 32, 40, 48, 56, 64, 80, 96, 112, 128);
 
+/// Trait to allow converting from itself (only implemented for a static str) into some useful
+/// type (which must implement `StaticHexConversion`).
 pub trait StaticHexInto {
+	/// Convert self (i.e. a static str) into the appropriate type. Use just like `Into::into`.
 	fn convert<T: StaticHexConversion>(self) -> T;
 }
 

substrate/wasm-runtime/polkadot/src/support/storable.rs

@@ -1,16 +1,39 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Stuff to do with the runtime's storage.
+
 use slicable::Slicable;
 use endiansensitive::EndianSensitive;
 use keyedvec::KeyedVec;
 use runtime_support::{self, twox_128, Vec};
 
+/// Trait for a value which may be stored in the storage DB.
 pub trait Storable {
+	/// Lookup the value in storage and deserialise, giving a default value if not found.
 	fn lookup_default(key: &[u8]) -> Self where Self: Sized + Default { Self::lookup(key).unwrap_or_else(Default::default) }
+	/// Lookup `Some` value in storage and deserialise; `None` if it's not there.
 	fn lookup(_key: &[u8]) -> Option<Self> where Self: Sized { unimplemented!() }
+	/// Place the value in storage under `key`.
 	fn store(&self, key: &[u8]);
 }
 
 // TODO: consider using blake256 to avoid possible eclipse attack.
 
+/// Remove `key` from storage.
 pub fn kill(key: &[u8]) { runtime_support::set_storage(&twox_128(key)[..], b""); }
 
 impl<T: Default + Sized + EndianSensitive> Storable for T {

substrate/wasm-runtime/polkadot/src/support/testing.rs

@@ -1,10 +1,30 @@
+// Copyright 2017 Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Polkadot is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Testing helpers.
+
 use runtime_support::{NoError, Externalities};
 use std::collections::HashMap;
 use primitives::AccountID;
 use statichex::StaticHexInto;
 
 #[derive(Debug, Default)]
+/// Simple externaties implementation.
 pub struct TestExternalities {
+	/// The storage map.
 	pub storage: HashMap<Vec<u8>, Vec<u8>>,
 }
 
@@ -29,16 +49,20 @@ macro_rules! map {
 	)
 }
 
+/// One account (to which we know the secret key).
 pub fn one() -> AccountID {
 	"2f8c6129d816cf51c374bc7f08c3e63ed156cf78aefb4a6550d97b87997977ee".convert()
 }
+/// Another account (secret key known).
 pub fn two() -> AccountID {
 	"d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a".convert()
 }
 
+/// Hex display, this time for no_std. See main codebase for documentation.
 pub struct HexDisplay<'a>(&'a [u8]);
 
 impl<'a> HexDisplay<'a> {
+	/// See main codebase for documentation.
 	pub fn from(d: &'a AsBytesRef) -> Self { HexDisplay(d.as_bytes_ref()) }
 }
 
@@ -51,7 +75,9 @@ impl<'a> ::std::fmt::Display for HexDisplay<'a> {
 	}
 }
 
+/// See main codebase for documentation.
 pub trait AsBytesRef {
+	/// See main codebase for documentation.
 	fn as_bytes_ref(&self) -> &[u8];
 }