Documentation.

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];
 }