Make Documentation Examples Compile (#2310)

* opening and closing links

* sudo example compiles

* add Aura after it was merged to master

* Timestamp doc testing passes

* Timestamp doc testing works, extraneous lines commented out

* balances

* remove extern crate line

* Removed unneeded code snippet from aura

* make consensus compiles

* executive compiles

* cleanup unnecessary lines

* staking (removed examples that are just copies of tests)

* Apply suggestions from code review

* unindent example

substrate/srml/aura/src/lib.rs

@@ -29,26 +29,6 @@
 //!
 //! - `slot_duration` - Determine the Aura slot-duration based on the Timestamp module configuration.
 //!
-//! ## Usage
-//!
-//! ### Prerequisites
-//!
-//! Use of this module implies selection of the Aura algorithm.
-//!
-//! ### Simple Code Snippet
-//!
-//! Instantiate a report of skipped authorities:
-//!
-//! ```rust,ignore
-//! let mut report = AuraReport {
-//! 	start_slot: 6, // The first skipped slot
-//! 	skipped: 3,   // The number of authorities skipped
-//! }
-//! ```
-//!
-//! See the `tests.rs` file in this module's directory for other simple code snippets that may make this module's
-//! functionalities clearer.
-//!
 //! ## Related Modules
 //!
 //! - [Staking](../srml_staking/index.html): The Staking module is called in Aura to enforce slashing

substrate/srml/balances/src/lib.rs

@@ -91,16 +91,13 @@
 //!
 //! The following examples show how to use the Balances module in your custom module.
 //!
-//! ### Example from the SRML
+//! ### Examples from the SRML
 //!
-//! The Contract module uses the `Currency` trait to handle gas.
+//! The Contract module uses the `Currency` trait to handle gas payment, and its types inherit from `Currency`:
 //!
-//! [(lib.rs)](https://github.com/paritytech/substrate/blob/master/srml/contract/src/lib.rs):
+//! ```
-//!
-//! ```ignore
-//! # extern crate srml_support;
 //! use srml_support::traits::Currency;
-//! # pub trait Trait: balances::Trait {
+//! # pub trait Trait: system::Trait {
 //! # 	type Currency: Currency<Self::AccountId>;
 //! # }
 //!
@@ -110,29 +107,33 @@
 //! # fn main() {}
 //!```
 //!
-//! [(gas.rs)](https://github.com/paritytech/substrate/blob/master/srml/contract/src/gas.rs):
+//! The Staking module uses the `LockableCurrency` trait to lock a stash account's funds:
 //!
-//! ```ignore
+//! ```
-//! use srml_support::traits::Currency;
+//! use srml_support::traits::{WithdrawReasons, LockableCurrency};
-//! # pub trait Trait: system::Trait {}
+//! use primitives::traits::Bounded;
+//! pub trait Trait: system::Trait {
+//! 	type Currency: LockableCurrency<Self::AccountId, Moment=Self::BlockNumber>;
+//! }
+//! # struct StakingLedger<T: Trait> {
+//! # 	stash: <T as system::Trait>::AccountId,
+//! # 	total: <<T as Trait>::Currency as srml_support::traits::Currency<<T as system::Trait>::AccountId>>::Balance,
+//! # 	phantom: std::marker::PhantomData<T>,
+//! # }
+//! # const STAKING_ID: [u8; 8] = *b"staking ";
 //!
-//! pub fn refund_unused_gas<T: Trait>(
+//! fn update_ledger<T: Trait>(
-//! 	transactor: &T::AccountId,
+//! 	controller: &T::AccountId,
-//! 	gas_meter: GasMeter<T>,
+//! 	ledger: &StakingLedger<T>
-//! 	imbalance: NegativeImbalanceOf<T>,
 //! ) {
-//! 	let gas_spent = gas_meter.spent();
+//! 	T::Currency::set_lock(
-//! 	let gas_left = gas_meter.gas_left();
+//! 		STAKING_ID,
-//!
+//! 		&ledger.stash,
-//! 	// Increase total spent gas.
+//! 		ledger.total,
-//! 	<GasSpent<T>>::mutate(|block_gas_spent| *block_gas_spent += gas_spent);
+//! 		T::BlockNumber::max_value(),
-//!
+//! 		WithdrawReasons::all()
-//! 	// Refund gas left by the price it was bought at.
+//! 	);
-//! 	let refund = <T::Gas as As<BalanceOf<T>>>::as_(gas_left) * gas_meter.gas_price;
+//! 	// <Ledger<T>>::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here.
-//! 	let refund_imbalance = T::Currency::deposit_creating(transactor, refund);
-//! 	if let Ok(imbalance) = imbalance.offset(refund_imbalance) {
-//! 		T::GasPayment::on_unbalanced(imbalance);
-//! 	}
 //! }
 //! # fn main() {}
 //! ```

substrate/srml/consensus/src/lib.rs

@@ -46,36 +46,28 @@
 //!
 //! ## Usage
 //!
-//! ### Prerequisites
-//!
-//! To use functionality from the consensus module, implement the specific Trait or function that you are invoking
-//! from the module:
-//!
-//! ```rust,ignore
-//! impl<T> for consensus::SomeTrait for Module<T> {
-//! 	/// required functions and types for trait included here
-//! 	/// more comprehensive example included below
-//! }
-//! ```
-//!
-//! Alternatively, to set the authorities:
-//!
-//! ```rust,ignore
-//! consensus::set_authorities(&[<authorities>]) // example included below
-//! ```
-//!
 //! ### Simple Code Snippet
 //!
 //! Set authorities:
 //!
-//! ```rust,ignore
+//! ```
-//! <consensus::Module<T>>::set_authorities(&[UintAuthorityId(4), UintAuthorityId(5), UintAuthorityId(6)])
+//! # use srml_consensus as consensus;
+//! # fn not_executed<T: consensus::Trait>() {
+//! # let authority1 = T::SessionKey::default();
+//! # let authority2 = T::SessionKey::default();
+//! <consensus::Module<T>>::set_authorities(&[authority1, authority2])
+//! # }
 //! ```
 //!
 //! Log changes in the authorities set:
 //!
-//! ```rust,ignore
+//! ```
-//! <consensus::Module<T>>::on_finalize(5); // finalize UintAuthorityId(5)
+//! # use srml_consensus as consensus;
+//! # use primitives::traits::Zero;
+//! # use primitives::traits::OnFinalize;
+//! # fn not_executed<T: consensus::Trait>() {
+//! <consensus::Module<T>>::on_finalize(T::BlockNumber::zero());
+//! # }
 //! ```
 //!
 //! ### Example from SRML
@@ -83,12 +75,21 @@
 //! In the staking module, the `consensus::OnOfflineReport` is implemented to monitor offline
 //! reporting among validators:
 //!
-//! ```rust,ignore
+//! ```
+//! # use srml_consensus as consensus;
+//! # trait Trait: consensus::Trait {
+//! # }
+//! #
+//! # srml_support::decl_module! {
+//! #     pub struct Module<T: Trait> for enum Call where origin: T::Origin {
+//! #     }
+//! # }
+//! #
 //! impl<T: Trait> consensus::OnOfflineReport<Vec<u32>> for Module<T> {
 //! 	fn handle_report(reported_indices: Vec<u32>) {
 //! 		for validator_index in reported_indices {
-//! 			let v = <session::Module<T>>::validators()[validator_index as usize].clone();
+//! 			// Get validator from session module
-//! 			Self::on_offline_validator(v, 1);
+//! 			// Process validator
 //! 		}
 //! 	}
 //! }
@@ -97,11 +98,15 @@
 //! In the GRANDPA module, we use `srml-consensus` to get the set of `next_authorities` before changing
 //! this set according to the consensus algorithm (which does not rotate sessions in the *normal* way):
 //!
-//! ```rust,ignore
+//! ```
+//! # use srml_consensus as consensus;
+//! # use consensus::Trait;
+//! # fn not_executed<T: consensus::Trait>() {
 //! let next_authorities = <consensus::Module<T>>::authorities()
 //! 			.into_iter()
 //! 			.map(|key| (key, 1)) // evenly-weighted.
 //! 			.collect::<Vec<(<T as Trait>::SessionKey, u64)>>();
+//! # }
 //! ```
 //!
 //! ## Related Modules

substrate/srml/executive/src/lib.rs

@@ -49,7 +49,16 @@
 //!
 //! `Executive` type declaration from the node template.
 //!
-//! ```ignore
+//! ```
+//! # use primitives::generic;
+//! # use srml_executive as executive;
+//! # pub struct UncheckedExtrinsic {};
+//! # pub struct Header {};
+//! # type Context = system::ChainContext<Runtime>;
+//! # pub type Block = generic::Block<Header, UncheckedExtrinsic>;
+//! # pub type Balances = u64;
+//! # pub type AllModules = u64;
+//! # pub enum Runtime {};
 //! /// Executive: handles dispatch to the various modules.
 //! pub type Executive = executive::Executive<Runtime, Block, Context, Balances, AllModules>;
 //! ```

substrate/srml/staking/src/lib.rs

@@ -127,42 +127,7 @@
 //!
 //! ## Usage
 //!
-//! ### Snippet: Bonding and Accepting Roles
+//! ### Example: Reporting Misbehavior
-//!
-//! An arbitrary account pair, given that the associated stash has the required funds,
-//! can become stakers via the following call:
-//!
-//! ```rust,ignore
-//! // Bond account 3 as stash.
-//! // Account 4 as controller.
-//! // Stash value of 1500 units.
-//! // Rewards get transferred to the controller account.
-//! Staking::bond(Origin::signed(3), 4, 1500, RewardDestination::Controller);
-//! ```
-//!
-//! To state desire to become a validator:
-//!
-//! ```rust,ignore
-//! // Controller account 4 states desire for validation with the given preferences.
-//! Staking::validate(Origin::signed(4), ValidatorPrefs::default());
-//! ```
-//!
-//! Similarly, to state desire in nominating:
-//!
-//! ```rust,ignore
-//! // Controller account 4 nominates for accounts 10 and 20.
-//! Staking::nominate(Origin::signed(4), vec![20, 10]);
-//! ```
-//!
-//! Finally, account 4 can withdraw from any of the above roles via
-//!
-//! ```rust,ignore
-//! Staking::chill(Origin::signed(4));
-//! ```
-//!
-//! You can find the equivalent of the above calls in your [Substrate UI](https://substrate-ui.parity.io).
-//!
-//! ### Snippet: Reporting Misbehavior
 //!
 //! ```
 //! use srml_support::{decl_module, dispatch::Result};

substrate/srml/timestamp/src/lib.rs

@@ -57,8 +57,9 @@
 //!
 //! ### Get current timestamp
 //!
-//! ```ignore
+//! ```
-//! use support::{decl_module, dispatch::Result};
+//! use srml_support::{decl_module, dispatch::Result};
+//! # use srml_timestamp as timestamp;
 //! use system::ensure_signed;
 //!
 //! pub trait Trait: timestamp::Trait {}
@@ -72,6 +73,7 @@
 //! 		}
 //! 	}
 //! }
+//! # fn main() {}
 //! ```
 //!
 //! ### Example from the SRML