Update Documentation (#2172)

* timestamp

* balances

* balances-remove-short-example

* system

* sudo (+missing period in balances)

* contract

* staking

* fix unclear definition in balances

* update after review

* update genesis-config-sudo link

Co-Authored-By: joepetrowski <25483142+joepetrowski@users.noreply.github.com>

* genesis

substrate/srml/system/src/lib.rs

@@ -14,38 +14,38 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! # System module
+//! # System Module
 //!
-//! The system module provides low-level access to core types and cross-cutting utilities.
+//! The System module provides low-level access to core types and cross-cutting utilities.
 //! It acts as the base layer for other SRML modules to interact with the Substrate framework components.
-//! To use it in your module, you should ensure your module's trait implies the system [`Trait`].
+//! To use it in your module, you need to implement the [`system::Trait`](./trait.Trait.html).
 //!
 //! ## Overview
 //!
-//! The system module defines the core data types used in a Substrate runtime.
-//! It also provides several utility functions (see [`Module`]) for other runtime modules.
+//! The System module defines the core data types used in a Substrate runtime.
+//! It also provides several utility functions (see [`Module`](./struct.Module.html)) for other runtime modules.
 //!
-//! In addition, it manages the storage items for extrinsics data, indexes, event record and digest items,
+//! In addition, it manages the storage items for extrinsics data, indexes, event records, and digest items,
 //! among other things that support the execution of the current block.
 //!
-//! It also handles low level tasks like depositing logs, basic set up and take down of
-//! temporary storage entries and access to previous block hashes.
+//! It also handles low-level tasks like depositing logs, basic set up and take down of
+//! temporary storage entries, and access to previous block hashes.
 //!
 //! ## Interface
 //!
-//! ### Dispatchable functions
+//! ### Dispatchable Functions
 //!
-//! The system module does not implement any dispatchable functions.
+//! The System module does not implement any dispatchable functions.
 //!
-//! ### Public functions
+//! ### Public Functions
 //!
-//! All public functions are available as part of the [`Module`] type.
+//! See the [`Module`](./struct.Module.html) struct for details of publicly available functions.
 //!
 //! ## Usage
 //!
 //! ### Prerequisites
 //!
-//! Import the system module and derive your module's configuration trait from the system trait.
+//! Import the System module and derive your module's configuration trait from the system trait.
 //!
 //! ### Example - Get random seed and extrinsic count for the current block
 //!
@@ -99,7 +99,7 @@ impl<AccountId> OnNewAccount<AccountId> for () {
 	fn on_new_account(_who: &AccountId) {}
 }
 
-/// Determinator to say whether a given account is unused.
+/// Determiner to say whether a given account is unused.
 pub trait IsDeadAccount<AccountId> {
 	/// Is the given account dead?
 	fn is_dead_account(who: &AccountId) -> bool;
@@ -168,7 +168,7 @@ pub trait Trait: 'static + Eq + Clone {
 	/// The aggregated event type of the runtime.
 	type Event: Parameter + Member + From<Event>;
 
-	/// A piece of information which can be part of the digest (as a digest item).
+	/// A piece of information that can be part of the digest (as a digest item).
 	type Log: From<Log<Self>> + Into<DigestItemOf<Self>>;
 }
 
@@ -176,7 +176,7 @@ pub type DigestItemOf<T> = <<T as Trait>::Digest as traits::Digest>::Item;
 
 decl_module! {
 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
-		/// Deposits an event onto this block's event record.
+		/// Deposits an event into this block's event record.
 		pub fn deposit_event(event: T::Event) {
 			let extrinsic_index = Self::extrinsic_index();
 			let phase = extrinsic_index.map_or(Phase::Finalization, |c| Phase::ApplyExtrinsic(c));
@@ -215,7 +215,7 @@ pub struct EventRecord<E: Parameter + Member> {
 }
 
 decl_event!(
-	/// Event for the system module.
+	/// Event for the System module.
 	pub enum Event {
 		/// An extrinsic completed successfully.
 		ExtrinsicSuccess,
@@ -224,13 +224,13 @@ decl_event!(
 	}
 );
 
-/// Origin for the system module.
+/// Origin for the System module.
 #[derive(PartialEq, Eq, Clone)]
 #[cfg_attr(feature = "std", derive(Debug))]
 pub enum RawOrigin<AccountId> {
 	/// The system itself ordained this dispatch to happen: this is the highest privilege level.
 	Root,
-	/// It is signed by some public key and we provide the AccountId.
+	/// It is signed by some public key and we provide the `AccountId`.
 	Signed(AccountId),
 	/// It is signed by nobody but included and agreed upon by the validators anyway: it's "inherently" true.
 	Inherent,
@@ -252,7 +252,7 @@ pub type Log<T> = RawLog<
 	<T as Trait>::Hash,
 >;
 
-/// A logs in this module.
+/// A log in this module.
 #[cfg_attr(feature = "std", derive(Serialize, Debug))]
 #[derive(Encode, Decode, PartialEq, Eq, Clone)]
 pub enum RawLog<Hash> {
@@ -299,7 +299,7 @@ decl_storage! {
 		AllExtrinsicsLen: Option<u32>;
 		/// Map of block numbers to block hashes.
 		pub BlockHash get(block_hash) build(|_| vec![(T::BlockNumber::zero(), hash69())]): map T::BlockNumber => T::Hash;
-		/// Extrinsics data for the current block (maps extrinsic's index to its data).
+		/// Extrinsics data for the current block (maps an extrinsic's index to its data).
 		ExtrinsicData get(extrinsic_data): map u32 => Vec<u8>;
 		/// Random seed of the current block.
 		RandomSeed get(random_seed) build(|_| T::Hash::default()): T::Hash;
@@ -388,7 +388,7 @@ impl<T: Trait> Module<T> {
 
 	/// Start the execution of a particular block.
 	pub fn initialize(number: &T::BlockNumber, parent_hash: &T::Hash, txs_root: &T::Hash) {
-		// populate environment.
+		// populate environment
 		storage::unhashed::put(well_known_keys::EXTRINSIC_INDEX, &0u32);
 		<Number<T>>::put(number);
 		<ParentHash<T>>::put(parent_hash);
@@ -412,7 +412,7 @@ impl<T: Trait> Module<T> {
 		let storage_changes_root = T::Hashing::storage_changes_root(parent_hash, number.as_() - 1);
 
 		// we can't compute changes trie root earlier && put it to the Digest
-		// because it will include all currently existing temporaries
+		// because it will include all currently existing temporaries.
 		if let Some(storage_changes_root) = storage_changes_root {
 			let item = RawLog::ChangesTrieRoot(storage_changes_root);
 			let item = <T as Trait>::Log::from(item).into();
@@ -424,7 +424,7 @@ impl<T: Trait> Module<T> {
 		<T::Header as traits::Header>::new(number, extrinsics_root, storage_root, parent_hash, digest)
 	}
 
-	/// Deposits a log and ensures it matches the blocks log data.
+	/// Deposits a log and ensures it matches the block's log data.
 	pub fn deposit_log(item: <T::Digest as traits::Digest>::Item) {
 		let mut l = <Digest<T>>::get();
 		traits::Digest::push(&mut l, item);
@@ -489,7 +489,7 @@ impl<T: Trait> Module<T> {
 	/// Note what the extrinsic data of the current extrinsic index is. If this is called, then
 	/// ensure `derive_extrinsics` is also called before block-building is completed.
 	///
-	/// NOTE this function is called only when the block is being constructed locally.
+	/// NOTE: This function is called only when the block is being constructed locally.
 	/// `execute_block` doesn't note any extrinsics.
 	pub fn note_extrinsic(encoded_xt: Vec<u8>) {
 		<ExtrinsicData<T>>::insert(Self::extrinsic_index().unwrap_or_default(), encoded_xt);
@@ -516,7 +516,7 @@ impl<T: Trait> Module<T> {
 		<ExtrinsicCount<T>>::put(extrinsic_index);
 	}
 
-	/// Remove all extrinsics data and save the extrinsics trie root.
+	/// Remove all extrinsic data and save the extrinsics trie root.
 	pub fn derive_extrinsics() {
 		let extrinsics = (0..<ExtrinsicCount<T>>::get().unwrap_or_default()).map(<ExtrinsicData<T>>::take).collect();
 		let xts_root = extrinsics_data_root::<T::Hashing>(extrinsics);