From 61e63a04fbb6b929fa7a38f69ee06f971d70d088 Mon Sep 17 00:00:00 2001 From: joe petrowski <25483142+joepetrowski@users.noreply.github.com> Date: Thu, 18 Apr 2019 14:53:02 +0200 Subject: [PATCH] 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 | 20 ---------- substrate/srml/balances/src/lib.rs | 55 ++++++++++++++-------------- substrate/srml/consensus/src/lib.rs | 57 ++++++++++++++++------------- substrate/srml/executive/src/lib.rs | 11 +++++- substrate/srml/staking/src/lib.rs | 37 +------------------ substrate/srml/timestamp/src/lib.rs | 6 ++- 6 files changed, 74 insertions(+), 112 deletions(-) diff --git a/substrate/srml/aura/src/lib.rs b/substrate/srml/aura/src/lib.rs index 1dec04df06..e5eb3674cd 100644 --- a/substrate/srml/aura/src/lib.rs +++ b/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 diff --git a/substrate/srml/balances/src/lib.rs b/substrate/srml/balances/src/lib.rs index 93ed2e1921..7f4743ffd4 100644 --- a/substrate/srml/balances/src/lib.rs +++ b/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; //! # } //! @@ -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; -//! # pub trait Trait: system::Trait {} +//! ``` +//! use srml_support::traits::{WithdrawReasons, LockableCurrency}; +//! use primitives::traits::Bounded; +//! pub trait Trait: system::Trait { +//! type Currency: LockableCurrency; +//! } +//! # struct StakingLedger { +//! # stash: ::AccountId, +//! # total: <::Currency as srml_support::traits::Currency<::AccountId>>::Balance, +//! # phantom: std::marker::PhantomData, +//! # } +//! # const STAKING_ID: [u8; 8] = *b"staking "; //! -//! pub fn refund_unused_gas( -//! transactor: &T::AccountId, -//! gas_meter: GasMeter, -//! imbalance: NegativeImbalanceOf, +//! fn update_ledger( +//! controller: &T::AccountId, +//! ledger: &StakingLedger //! ) { -//! let gas_spent = gas_meter.spent(); -//! let gas_left = gas_meter.gas_left(); -//! -//! // Increase total spent gas. -//! >::mutate(|block_gas_spent| *block_gas_spent += gas_spent); -//! -//! // Refund gas left by the price it was bought at. -//! let refund = >>::as_(gas_left) * gas_meter.gas_price; -//! let refund_imbalance = T::Currency::deposit_creating(transactor, refund); -//! if let Ok(imbalance) = imbalance.offset(refund_imbalance) { -//! T::GasPayment::on_unbalanced(imbalance); -//! } +//! T::Currency::set_lock( +//! STAKING_ID, +//! &ledger.stash, +//! ledger.total, +//! T::BlockNumber::max_value(), +//! WithdrawReasons::all() +//! ); +//! // >::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here. //! } //! # fn main() {} //! ``` diff --git a/substrate/srml/consensus/src/lib.rs b/substrate/srml/consensus/src/lib.rs index d5ee023c93..5637f458c1 100644 --- a/substrate/srml/consensus/src/lib.rs +++ b/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 for consensus::SomeTrait for Module { -//! /// required functions and types for trait included here -//! /// more comprehensive example included below -//! } -//! ``` -//! -//! Alternatively, to set the authorities: -//! -//! ```rust,ignore -//! consensus::set_authorities(&[]) // example included below -//! ``` -//! //! ### Simple Code Snippet //! //! Set authorities: //! -//! ```rust,ignore -//! >::set_authorities(&[UintAuthorityId(4), UintAuthorityId(5), UintAuthorityId(6)]) +//! ``` +//! # use srml_consensus as consensus; +//! # fn not_executed() { +//! # let authority1 = T::SessionKey::default(); +//! # let authority2 = T::SessionKey::default(); +//! >::set_authorities(&[authority1, authority2]) +//! # } //! ``` //! //! Log changes in the authorities set: //! -//! ```rust,ignore -//! >::on_finalize(5); // finalize UintAuthorityId(5) +//! ``` +//! # use srml_consensus as consensus; +//! # use primitives::traits::Zero; +//! # use primitives::traits::OnFinalize; +//! # fn not_executed() { +//! >::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 for enum Call where origin: T::Origin { +//! # } +//! # } +//! # //! impl consensus::OnOfflineReport> for Module { //! fn handle_report(reported_indices: Vec) { //! for validator_index in reported_indices { -//! let v = >::validators()[validator_index as usize].clone(); -//! Self::on_offline_validator(v, 1); +//! // Get validator from session module +//! // 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() { //! let next_authorities = >::authorities() //! .into_iter() //! .map(|key| (key, 1)) // evenly-weighted. //! .collect::::SessionKey, u64)>>(); +//! # } //! ``` //! //! ## Related Modules diff --git a/substrate/srml/executive/src/lib.rs b/substrate/srml/executive/src/lib.rs index a33458a910..d0fae78105 100644 --- a/substrate/srml/executive/src/lib.rs +++ b/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; +//! # pub type Block = generic::Block; +//! # pub type Balances = u64; +//! # pub type AllModules = u64; +//! # pub enum Runtime {}; //! /// Executive: handles dispatch to the various modules. //! pub type Executive = executive::Executive; //! ``` diff --git a/substrate/srml/staking/src/lib.rs b/substrate/srml/staking/src/lib.rs index c58eb593f6..6a67b503dc 100644 --- a/substrate/srml/staking/src/lib.rs +++ b/substrate/srml/staking/src/lib.rs @@ -127,42 +127,7 @@ //! //! ## Usage //! -//! ### Snippet: Bonding and Accepting Roles -//! -//! 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 +//! ### Example: Reporting Misbehavior //! //! ``` //! use srml_support::{decl_module, dispatch::Result}; diff --git a/substrate/srml/timestamp/src/lib.rs b/substrate/srml/timestamp/src/lib.rs index 9b72a1ac9b..df89d0c1ff 100644 --- a/substrate/srml/timestamp/src/lib.rs +++ b/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