Add missing docs to sr-primitives. (#1531)

substrate/core/sr-primitives/src/generic/digest.rs

@@ -23,9 +23,11 @@ use traits::{self, Member, DigestItem as DigestItemT, MaybeHash};
 
 use substrate_primitives::hash::H512 as Signature;
 
+/// Generic header digest.
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug, Serialize))]
 pub struct Digest<Item> {
+	/// A list of logs in the digest.
 	pub logs: Vec<Item>,
 }
 
@@ -175,6 +177,7 @@ impl<Hash: Decode, AuthorityId: Decode> Decode for DigestItem<Hash, AuthorityId>
 }
 
 impl<'a, Hash: Codec + Member, AuthorityId: Codec + Member> DigestItemRef<'a, Hash, AuthorityId> {
+	/// Cast this digest item into `AuthoritiesChange`.
 	pub fn as_authorities_change(&self) -> Option<&'a [AuthorityId]> {
 		match *self {
 			DigestItemRef::AuthoritiesChange(ref authorities) => Some(authorities),
@@ -182,6 +185,7 @@ impl<'a, Hash: Codec + Member, AuthorityId: Codec + Member> DigestItemRef<'a, Ha
 		}
 	}
 
+	/// Cast this digest item into `ChangesTrieRoot`.
 	pub fn as_changes_trie_root(&self) -> Option<&'a Hash> {
 		match *self {
 			DigestItemRef::ChangesTrieRoot(ref changes_trie_root) => Some(changes_trie_root),

substrate/core/sr-primitives/src/lib.rs

@@ -17,6 +17,8 @@
 //! System manager: Handles all of the top-level stuff; executing block/transaction, setting code
 //! and depositing logs.
 
+#![warn(missing_docs)]
+
 #![cfg_attr(not(feature = "std"), no_std)]
 
 #[cfg(feature = "std")]
@@ -60,6 +62,7 @@ pub mod traits;
 pub mod generic;
 pub mod transaction_validity;
 
+/// Justification type.
 pub type Justification = Vec<u8>;
 
 use traits::{Verify, Lazy};
@@ -96,11 +99,15 @@ pub type ChildrenStorageMap = HashMap<Vec<u8>, StorageMap>;
 /// Complex storage builder stuff.
 #[cfg(feature = "std")]
 pub trait BuildStorage {
+	/// Hash given slice.
+	///
+	/// Default to xx128 hashing.
 	fn hash(data: &[u8]) -> [u8; 16] {
 		let r = runtime_io::twox_128(data);
 		trace!(target: "build_storage", "{} <= {}", substrate_primitives::hexdisplay::HexDisplay::from(&r), ascii_format(data));
 		r
 	}
+	/// Build the storage out of this builder.
 	fn build_storage(self) -> Result<(StorageMap, ChildrenStorageMap), String>;
 }
 
@@ -118,15 +125,19 @@ pub struct Permill(u32);
 
 // TODO: impl Mul<Permill> for N where N: As<usize>
 impl Permill {
+	/// Multiplication.
 	pub fn times<N: traits::As<u64> + ::rstd::ops::Mul<N, Output=N> + ::rstd::ops::Div<N, Output=N>>(self, b: N) -> N {
 		// TODO: handle overflows
 		b * <N as traits::As<u64>>::sa(self.0 as u64) / <N as traits::As<u64>>::sa(1000000)
 	}
 
+	/// Wraps the argument into `Permill` type.
 	pub fn from_millionths(x: u32) -> Permill { Permill(x) }
 
+	/// Converts percents into `Permill`.
 	pub fn from_percent(x: u32) -> Permill { Permill(x * 10_000) }
 
+	/// Converts a fraction into `Permill`.
 	#[cfg(feature = "std")]
 	pub fn from_fraction(x: f64) -> Permill { Permill((x * 1_000_000.0) as u32) }
 }

substrate/core/sr-primitives/src/testing.rs

@@ -25,6 +25,7 @@ use generic::DigestItem as GenDigestItem;
 pub use substrate_primitives::{H256, Ed25519AuthorityId};
 use substrate_primitives::U256;
 
+/// Authority Id
 #[derive(Default, PartialEq, Eq, Clone, Decode, Encode, Debug)]
 #[cfg_attr(feature = "std", derive(Serialize, Deserialize))]
 pub struct UintAuthorityId(pub u64);
@@ -35,17 +36,20 @@ impl Into<Ed25519AuthorityId> for UintAuthorityId {
 	}
 }
 
+/// Converter between u64 and the AuthorityId wrapper type.
 pub struct ConvertUintAuthorityId;
 impl Convert<u64, UintAuthorityId> for ConvertUintAuthorityId {
 	fn convert(a: u64) -> UintAuthorityId {
 		UintAuthorityId(a)
 	}
 }
-
+/// Digest item
 pub type DigestItem = GenDigestItem<H256, Ed25519AuthorityId>;
 
+/// Header Digest
 #[derive(Default, PartialEq, Eq, Clone, Serialize, Debug, Encode, Decode)]
 pub struct Digest {
+	/// Generated logs
 	pub logs: Vec<DigestItem>,
 }
 
@@ -66,14 +70,20 @@ impl traits::Digest for Digest {
 	}
 }
 
+/// Block Header
 #[derive(PartialEq, Eq, Clone, Serialize, Debug, Encode, Decode)]
 #[serde(rename_all = "camelCase")]
 #[serde(deny_unknown_fields)]
 pub struct Header {
+	/// Parent hash
 	pub parent_hash: H256,
+	/// Block Number
 	pub number: u64,
+	/// Post-execution state trie root
 	pub state_root: H256,
+	/// Merkle root of block's extrinsics
 	pub extrinsics_root: H256,
+	/// Digest items
 	pub digest: Digest,
 }
 
@@ -123,6 +133,7 @@ impl<'a> Deserialize<'a> for Header {
 	}
 }
 
+/// An opaque extrinsic wrapper type.
 #[derive(PartialEq, Eq, Clone, Debug, Encode, Decode)]
 pub struct ExtrinsicWrapper<Xt>(Xt);
 
@@ -153,9 +164,12 @@ impl<Xt> Deref for ExtrinsicWrapper<Xt> {
 	}
 }
 
+/// Testing block
 #[derive(PartialEq, Eq, Clone, Serialize, Debug, Encode, Decode)]
 pub struct Block<Xt> {
+	/// Block header
 	pub header: Header,
+	/// List of extrinsics
 	pub extrinsics: Vec<Xt>,
 }
 
@@ -185,6 +199,7 @@ impl<'a, Xt> Deserialize<'a> for Block<Xt> where Block<Xt>: Decode {
 	}
 }
 
+/// Test transaction
 #[derive(PartialEq, Eq, Clone, Encode, Decode)]
 pub struct TestXt<Call>(pub Option<u64>, pub u64, pub Call);
 

substrate/core/sr-primitives/src/traits.rs

@@ -36,6 +36,9 @@ use rstd::ops::{
 
 /// A lazy value.
 pub trait Lazy<T: ?Sized> {
+	/// Get a reference to the underlying value.
+	///
+	/// This will compute the value if the function is invoked for the first time.
 	fn get(&mut self) -> &T;
 }
 
@@ -53,7 +56,9 @@ pub trait Verify {
 
 /// Some sort of check on the origin is performed by this object.
 pub trait EnsureOrigin<OuterOrigin> {
+	/// A return type.
 	type Success;
+	/// Perform the origin check.
 	fn ensure_origin(o: OuterOrigin) -> result::Result<Self::Success, &'static str>;
 }
 
@@ -79,6 +84,7 @@ pub trait StaticLookup {
 	fn lookup(s: Self::Source) -> result::Result<Self::Target, &'static str>;
 }
 
+/// A lookup implementation returning the input value.
 #[derive(Default)]
 pub struct IdentityLookup<T>(PhantomData<T>);
 impl<T: Codec + Clone + PartialEq + MaybeDebug> StaticLookup for IdentityLookup<T> {
@@ -162,6 +168,7 @@ macro_rules! impl_numerics {
 
 impl_numerics!(u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize);
 
+/// A structure that performs identity conversion.
 pub struct Identity;
 impl<T> Convert<T, T> for Identity {
 	fn convert(a: T) -> T { a }
@@ -170,13 +177,7 @@ impl<T> Convert<T, ()> for () {
 	fn convert(_: T) -> () { () }
 }
 
-pub trait RefInto<T> {
-	fn ref_into(&self) -> &T;
-}
-impl<T> RefInto<T> for T {
-	fn ref_into(&self) -> &T { &self }
-}
-
+/// A meta trait for arithmetic.
 pub trait SimpleArithmetic:
 	Zero + One + IntegerSquareRoot + As<u64> +
 	Add<Self, Output = Self> + AddAssign<Self> +
@@ -227,6 +228,7 @@ impl<T: Default + Eq + PartialEq> Clear for T {
 	fn clear() -> Self { Default::default() }
 }
 
+/// A meta trait for all bit ops.
 pub trait SimpleBitOps:
 	Sized + Clear +
 	rstd::ops::BitOr<Self, Output = Self> +
@@ -348,6 +350,7 @@ impl Hash for BlakeTwo256 {
 
 /// Something that can be checked for equality and printed out to a debug channel if bad.
 pub trait CheckEqual {
+	/// Perform the equality check.
 	fn check_equal(&self, other: &Self);
 }
 
@@ -388,76 +391,79 @@ impl<I> CheckEqual for I where I: DigestItem {
 	}
 }
 
+/// A type that implements Serialize and Debug when in std environment.
 #[cfg(feature = "std")]
 pub trait MaybeSerializeDebugButNotDeserialize: Serialize + Debug {}
 #[cfg(feature = "std")]
 impl<T: Serialize + Debug> MaybeSerializeDebugButNotDeserialize for T {}
 
+/// A type that implements Serialize and Debug when in std environment.
 #[cfg(not(feature = "std"))]
 pub trait MaybeSerializeDebugButNotDeserialize {}
 #[cfg(not(feature = "std"))]
 impl<T> MaybeSerializeDebugButNotDeserialize for T {}
 
+/// A type that implements Serialize when in std environment.
 #[cfg(feature = "std")]
 pub trait MaybeSerialize: Serialize {}
 #[cfg(feature = "std")]
 impl<T: Serialize> MaybeSerialize for T {}
 
+/// A type that implements Serialize when in std environment.
 #[cfg(not(feature = "std"))]
 pub trait MaybeSerialize {}
 #[cfg(not(feature = "std"))]
 impl<T> MaybeSerialize for T {}
 
+/// A type that implements Serialize, DeserializeOwned and Debug when in std environment.
 #[cfg(feature = "std")]
 pub trait MaybeSerializeDebug: Serialize + DeserializeOwned + Debug {}
 #[cfg(feature = "std")]
 impl<T: Serialize + DeserializeOwned + Debug> MaybeSerializeDebug for T {}
 
+/// A type that implements Serialize, DeserializeOwned and Debug when in std environment.
 #[cfg(not(feature = "std"))]
 pub trait MaybeSerializeDebug {}
 #[cfg(not(feature = "std"))]
 impl<T> MaybeSerializeDebug for T {}
 
+/// A type that implements Debug when in std environment.
 #[cfg(feature = "std")]
 pub trait MaybeDebug: Debug {}
 #[cfg(feature = "std")]
 impl<T: Debug> MaybeDebug for T {}
 
+/// A type that implements Debug when in std environment.
 #[cfg(not(feature = "std"))]
 pub trait MaybeDebug {}
 #[cfg(not(feature = "std"))]
 impl<T> MaybeDebug for T {}
 
+/// A type that implements Display when in std environment.
 #[cfg(feature = "std")]
 pub trait MaybeDisplay: Display {}
 #[cfg(feature = "std")]
 impl<T: Display> MaybeDisplay for T {}
 
+/// A type that implements Display when in std environment.
 #[cfg(not(feature = "std"))]
 pub trait MaybeDisplay {}
 #[cfg(not(feature = "std"))]
 impl<T> MaybeDisplay for T {}
 
+/// A type that implements Hash when in std environment.
 #[cfg(feature = "std")]
 pub trait MaybeHash: ::rstd::hash::Hash {}
 #[cfg(feature = "std")]
 impl<T: ::rstd::hash::Hash> MaybeHash for T {}
 
+/// A type that implements Hash when in std environment.
 #[cfg(not(feature = "std"))]
 pub trait MaybeHash {}
 #[cfg(not(feature = "std"))]
 impl<T> MaybeHash for T {}
 
-#[cfg(feature = "std")]
-pub trait MaybeDecode: ::codec::Decode {}
-#[cfg(feature = "std")]
-impl<T: ::codec::Decode> MaybeDecode for T {}
-
-#[cfg(not(feature = "std"))]
-pub trait MaybeDecode {}
-#[cfg(not(feature = "std"))]
-impl<T> MaybeDecode for T {}
-
+/// A type that can be used in runtime structures.
 pub trait Member: Send + Sync + Sized + MaybeDebug + Eq + PartialEq + Clone + 'static {}
 impl<T: Send + Sync + Sized + MaybeDebug + Eq + PartialEq + Clone + 'static> Member for T {}
 
@@ -467,11 +473,16 @@ impl<T: Send + Sync + Sized + MaybeDebug + Eq + PartialEq + Clone + 'static> Mem
 ///
 /// You can also create a `new` one from those fields.
 pub trait Header: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDeserialize + 'static {
+	/// Header number.
 	type Number: Member + MaybeSerializeDebug + ::rstd::hash::Hash + Copy + MaybeDisplay + SimpleArithmetic + Codec;
+	/// Header hash type
 	type Hash: Member + MaybeSerializeDebug + ::rstd::hash::Hash + Copy + MaybeDisplay + Default + SimpleBitOps + Codec + AsRef<[u8]> + AsMut<[u8]>;
+	/// Hashing algorithm
 	type Hashing: Hash<Output = Self::Hash>;
+	/// Digest type
 	type Digest: Digest<Hash = Self::Hash> + Codec;
 
+	/// Creates new header.
 	fn new(
 		number: Self::Number,
 		extrinsics_root: Self::Hash,
@@ -480,23 +491,34 @@ pub trait Header: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDe
 		digest: Self::Digest
 	) -> Self;
 
+	/// Returns a reference to the header number.
 	fn number(&self) -> &Self::Number;
+	/// Sets the header number.
 	fn set_number(&mut self, Self::Number);
 
+	/// Returns a reference to the extrinsics root.
 	fn extrinsics_root(&self) -> &Self::Hash;
+	/// Sets the extrinsic root.
 	fn set_extrinsics_root(&mut self, Self::Hash);
 
+	/// Returns a reference to the state root.
 	fn state_root(&self) -> &Self::Hash;
+	/// Sets the state root.
 	fn set_state_root(&mut self, Self::Hash);
 
+	/// Returns a reference to the parent hash.
 	fn parent_hash(&self) -> &Self::Hash;
+	/// Sets the parent hash.
 	fn set_parent_hash(&mut self, Self::Hash);
 
+	/// Returns a reference to the digest.
 	fn digest(&self) -> &Self::Digest;
 	/// Get a mutable reference to the digest.
 	fn digest_mut(&mut self) -> &mut Self::Digest;
+	/// Sets the digest.
 	fn set_digest(&mut self, Self::Digest);
 
+	/// Returns the hash of the header.
 	fn hash(&self) -> Self::Hash {
 		<Self::Hashing as Hash>::hash_of(self)
 	}
@@ -507,14 +529,22 @@ pub trait Header: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDe
 ///
 /// You can get an iterator over each of the `extrinsics` and retrieve the `header`.
 pub trait Block: Clone + Send + Sync + Codec + Eq + MaybeSerializeDebugButNotDeserialize + 'static {
+	/// Type of extrinsics.
 	type Extrinsic: Member + Codec + Extrinsic + MaybeSerialize;
+	/// Header type.
 	type Header: Header<Hash=Self::Hash>;
+	/// Block hash type.
 	type Hash: Member + MaybeSerializeDebug + ::rstd::hash::Hash + Copy + MaybeDisplay + Default + SimpleBitOps + Codec + AsRef<[u8]> + AsMut<[u8]>;
 
+	/// Returns a reference to the header.
 	fn header(&self) -> &Self::Header;
+	/// Returns a reference to the list of extrinsics.
 	fn extrinsics(&self) -> &[Self::Extrinsic];
+	/// Split the block into header and list of extrinsics.
 	fn deconstruct(self) -> (Self::Header, Vec<Self::Extrinsic>);
+	/// Creates new block from header and extrinsics.
 	fn new(header: Self::Header, extrinsics: Vec<Self::Extrinsic>) -> Self;
+	/// Returns the hash of the block.
 	fn hash(&self) -> Self::Hash {
 		<<Self::Header as Header>::Hashing as Hash>::hash_of(self.header())
 	}
@@ -571,24 +601,32 @@ impl<T: BlindCheckable, Context> Checkable<Context> for T {
 }
 
 /// An "executable" piece of information, used by the standard Substrate Executive in order to
-/// enact a piece of extrinsic information by marshalling and dispatching to a named functioon
+/// enact a piece of extrinsic information by marshalling and dispatching to a named function
 /// call.
 ///
 /// Also provides information on to whom this information is attributable and an index that allows
 /// each piece of attributable information to be disambiguated.
 pub trait Applyable: Sized + Send + Sync {
+	/// Id of the account that is responsible for this piece of information (sender).
 	type AccountId: Member + MaybeDisplay;
+	/// Index allowing to disambiguate other `Applyable`s from the same `AccountId`.
 	type Index: Member + MaybeDisplay + SimpleArithmetic;
+	/// Function call.
 	type Call: Member;
+	/// Returns a reference to the index if any.
 	fn index(&self) -> Option<&Self::Index>;
+	/// Returns a reference to the sender if any.
 	fn sender(&self) -> Option<&Self::AccountId>;
+	/// Deconstructs into function call and sender.
 	fn deconstruct(self) -> (Self::Call, Option<Self::AccountId>);
 }
 
 /// Something that acts like a `Digest` - it can have `Log`s `push`ed onto it and these `Log`s are
 /// each `Codec`.
 pub trait Digest: Member + MaybeSerializeDebugButNotDeserialize + Default {
+	/// Hash of the items.
 	type Hash: Member;
+	/// Digest item type.
 	type Item: DigestItem<Hash = Self::Hash>;
 
 	/// Get reference to all digest items.
@@ -611,7 +649,9 @@ pub trait Digest: Member + MaybeSerializeDebugButNotDeserialize + Default {
 ///
 /// If the runtime does not supports some 'system' items, use `()` as a stub.
 pub trait DigestItem: Codec + Member + MaybeSerializeDebugButNotDeserialize {
+	/// `ChangesTrieRoot` payload.
 	type Hash: Member;
+	/// `AuthorityChange` payload.
 	type AuthorityId: Member + MaybeHash + codec::Encode + codec::Decode;
 
 	/// Returns Some if the entry is the `AuthoritiesChange` entry.

substrate/core/sr-primitives/src/transaction_validity.rs

@@ -32,12 +32,33 @@ pub type TransactionTag = Vec<u8>;
 #[derive(Clone, PartialEq, Eq, Encode, Decode)]
 #[cfg_attr(feature = "std", derive(Debug))]
 pub enum TransactionValidity {
+	/// Transaction is invalid. Details are described by the error code.
 	Invalid,
+	/// Transaction is valid.
 	Valid {
+		/// Priority of the transaction.
+		///
+		/// Priority determines the ordering of two transactions that have all
+		/// their dependencies (required tags) satisfied.
 		priority: TransactionPriority,
+		/// Transaction dependencies
+		///
+		/// A non-empty list signifies that some other transactions which provide
+		/// given tags are required to be included before that one.
 		requires: Vec<TransactionTag>,
+		/// Provided tags
+		///
+		/// A list of tags this transaction provides. Successfuly importing the transaction
+		/// will enable other transactions that depend on (require) those tags to be included as well.
+		/// Provided and requried tags allow Substrate to build a dependency graph of transactions
+		/// and import them in the right (linear) order.
 		provides: Vec<TransactionTag>,
-		longevity: TransactionLongevity
+		/// Transaction longevity
+		///
+		/// Longevity describes minimum number of blocks the validity is correct.
+		/// After this period transaction should be removed from the pool or revalidated.
+		longevity: TransactionLongevity,
 	},
+	/// Transaction validity can't be determined.
 	Unknown,
 }