From 129803efd2107f07972395ce75fbcadc480fb376 Mon Sep 17 00:00:00 2001 From: joe petrowski <25483142+joepetrowski@users.noreply.github.com> Date: Wed, 17 Apr 2019 13:40:13 +0200 Subject: [PATCH] Make existing docs more consistent (#2307) * opening and closing links * sudo example compiles * add Aura after it was merged to master * remove extern crate line --- substrate/srml/aura/src/lib.rs | 11 ++++--- substrate/srml/balances/src/lib.rs | 34 ++++++++++---------- substrate/srml/consensus/src/lib.rs | 22 ++++++++----- substrate/srml/contract/src/lib.rs | 12 +++---- substrate/srml/staking/src/lib.rs | 26 +++++++-------- substrate/srml/sudo/src/lib.rs | 49 ++++------------------------- substrate/srml/system/src/lib.rs | 3 +- substrate/srml/timestamp/src/lib.rs | 13 +++----- 8 files changed, 67 insertions(+), 103 deletions(-) diff --git a/substrate/srml/aura/src/lib.rs b/substrate/srml/aura/src/lib.rs index fc1830088d..1dec04df06 100644 --- a/substrate/srml/aura/src/lib.rs +++ b/substrate/srml/aura/src/lib.rs @@ -16,6 +16,9 @@ //! # Aura Module //! +//! - [`aura::Trait`](./trait.Trait.html) +//! - [`Module`](./struct.Module.html) +//! //! ## Overview //! //! The Aura module extends Aura consensus by managing offline reporting. @@ -24,7 +27,7 @@ //! //! ### Public Functions //! -//! See the [`Module`](./struct.Module.html) struct for details on publicly available functions. +//! - `slot_duration` - Determine the Aura slot-duration based on the Timestamp module configuration. //! //! ## Usage //! @@ -48,12 +51,12 @@ //! //! ## Related Modules //! -//! - [`staking`](../srml_staking/index.html): The Staking module is called in Aura to enforce slashing +//! - [Staking](../srml_staking/index.html): The Staking module is called in Aura to enforce slashing //! if validators miss a certain number of slots (see the [`StakingSlasher`](./struct.StakingSlasher.html) //! struct and associated method). -//! - [`timestamp`](../srml_timestamp/index.html): The Timestamp module is used in Aura to track +//! - [Timestamp](../srml_timestamp/index.html): The Timestamp module is used in Aura to track //! consensus rounds (via `slots`). -//! - [`consensus`](../srml_consensus/index.html): The Consensus module does not relate directly to Aura, +//! - [Consensus](../srml_consensus/index.html): The Consensus module does not relate directly to Aura, //! but serves to manage offline reporting by implementing `ProvideInherent` in a similar way. //! //! ## References diff --git a/substrate/srml/balances/src/lib.rs b/substrate/srml/balances/src/lib.rs index 5c2de04c03..93ed2e1921 100644 --- a/substrate/srml/balances/src/lib.rs +++ b/substrate/srml/balances/src/lib.rs @@ -17,8 +17,10 @@ //! # Balances Module //! //! The Balances module provides functionality for handling accounts and balances. -//! To use it in your runtime, you need to implement the [`balances::Trait`](./trait.Trait.html). -//! Dispatchable functions are documented as part of the [`Call`](./enum.Call.html) enum. +//! +//! - [`balances::Trait`](./trait.Trait.html) +//! - [`Call`](./enum.Call.html) +//! - [`Module`](./struct.Module.html) //! //! ## Overview //! @@ -81,14 +83,10 @@ //! - `transfer` - Transfer some liquid free balance to another account. //! - `set_balance` - Set the balances of a given account. The origin of this call must be root. //! -//! See the [`Call`](./enum.Call.html) enum and its associated variants for details of each function. -//! //! ### Public Functions //! //! - `vesting_balance` - Get the amount that is currently being vested and cannot be transferred out of this account. //! -//! See the [`Module`](./struct.Module.html) struct for details of publicly available functions. -//! //! ## Usage //! //! The following examples show how to use the Balances module in your custom module. @@ -99,17 +97,24 @@ //! //! [(lib.rs)](https://github.com/paritytech/substrate/blob/master/srml/contract/src/lib.rs): //! -//! ```rust,ignore -//! use srml_support::traits::Currency +//! ```ignore +//! # extern crate srml_support; +//! use srml_support::traits::Currency; +//! # pub trait Trait: balances::Trait { +//! # type Currency: Currency; +//! # } //! //! pub type BalanceOf = <::Currency as Currency<::AccountId>>::Balance; //! pub type NegativeImbalanceOf = <::Currency as Currency<::AccountId>>::NegativeImbalance; +//! +//! # fn main() {} //!``` //! //! [(gas.rs)](https://github.com/paritytech/substrate/blob/master/srml/contract/src/gas.rs): //! -//! ```rust,ignore -//! use srml_support::traits::Currency +//! ```ignore +//! use srml_support::traits::Currency; +//! # pub trait Trait: system::Trait {} //! //! pub fn refund_unused_gas( //! transactor: &T::AccountId, @@ -129,17 +134,12 @@ //! T::GasPayment::on_unbalanced(imbalance); //! } //! } +//! # fn main() {} //! ``` //! //! ## Genesis config //! -//! The Balances module depends on the genesis configuration. See the [`GenesisConfig`](./struct.GenesisConfig.html) -//! struct for a list of attributes that can be provided. -//! -//! ## Related Modules -//! -//! - [`system`](../srml_system/index.html) -//! - [`srml_support`](../srml_support/index.html) +//! The Balances module depends on the [`GenesisConfig`](./struct.GenesisConfig.html). #![cfg_attr(not(feature = "std"), no_std)] diff --git a/substrate/srml/consensus/src/lib.rs b/substrate/srml/consensus/src/lib.rs index 68faf88382..d5ee023c93 100644 --- a/substrate/srml/consensus/src/lib.rs +++ b/substrate/srml/consensus/src/lib.rs @@ -16,6 +16,10 @@ //! # Consensus Module //! +//! - [`consensus::Trait`](./trait.Trait.html) +//! - [`Call`](./enum.Call.html) +//! - [`Module`](./struct.Module.html) +//! //! ## Overview //! //! The consensus module manages the authority set for the native code. It provides support for reporting offline @@ -33,11 +37,12 @@ //! - `set_code` - Set the new code. //! - `set_storage` - Set some items of storage. //! -//! Please refer to the [`Call`](./enum.Call.html) enum and its associated variants for documentation on each function. -//! //! ### Public Functions //! -//! See the [module](./struct.Module.html) for details on publicly available functions. +//! - `authorities` - Get the current set of authorities. These are the session keys. +//! - `set_authorities` - Set the current set of authorities' session keys. +//! - `set_authority_count` - Set the total number of authorities. +//! - `set_authority` - Set a single authority by index. //! //! ## Usage //! @@ -101,11 +106,11 @@ //! //! ## Related Modules //! -//! - [`staking`](../srml_staking/index.html): This module uses `srml-consensus` to monitor offline +//! - [Staking](../srml_staking/index.html): This module uses `srml-consensus` to monitor offline //! reporting among validators. -//! - [`aura`](../srml_aura/index.html): This module does not relate directly to `srml-consensus`, +//! - [Aura](../srml_aura/index.html): This module does not relate directly to `srml-consensus`, //! but serves to manage offline reporting for the Aura consensus algorithm with its own `handle_report` method. -//! - [`grandpa`](../srml_grandpa/index.html): Although GRANDPA does its own voter-set management, +//! - [Grandpa](../srml_grandpa/index.html): Although GRANDPA does its own voter-set management, //! it has a mode where it can track `consensus`, if desired. //! //! ## References @@ -339,7 +344,8 @@ impl Module { AuthorityStorageVec::::items() } - /// Set the current set of authorities' session keys. + /// Set the current set of authorities' session keys. Will not exceed the current + /// authorities count, even if the given `authorities` is longer. /// /// Called by `rotate_session` only. pub fn set_authorities(authorities: &[T::SessionKey]) { @@ -350,7 +356,7 @@ impl Module { } } - /// Set a single authority by index. + /// Set the total number of authorities. pub fn set_authority_count(count: u32) { Self::save_original_authorities(None); AuthorityStorageVec::::set_count(count); diff --git a/substrate/srml/contract/src/lib.rs b/substrate/srml/contract/src/lib.rs index ac3d503177..42bdf3240c 100644 --- a/substrate/srml/contract/src/lib.rs +++ b/substrate/srml/contract/src/lib.rs @@ -17,7 +17,9 @@ //! # Contract Module //! //! The Contract module provides functionality for the runtime to deploy and execute WebAssembly smart-contracts. -//! To use it in your runtime, you need to implement the [`contracts::Trait`](./trait.Trait.html). +//! +//! - [`contract::Trait`](./trait.Trait.html) +//! - [`Call`](./enum.Call.html) //! //! ## Overview //! @@ -61,12 +63,6 @@ //! This creates a new smart contract account and calls its contract deploy handler to initialize the contract. //! * `call` - Makes a call to an account, optionally transferring some balance. //! -//! See the [`Call`](./enum.Call.html) enum and its associated variants for details of each function. -//! -//! ### Public functions -//! -//! See the [`Module`](./struct.Module.html) struct for details on publicly available functions. -//! //! ## Usage //! //! The Contract module is a work in progress. The following examples show how this Contract module can be @@ -77,7 +73,7 @@ //! //! ## Related Modules //! -//! * [`Balances`](../srml_balances/index.html) +//! * [Balances](../srml_balances/index.html) #![cfg_attr(not(feature = "std"), no_std)] diff --git a/substrate/srml/staking/src/lib.rs b/substrate/srml/staking/src/lib.rs index 3e85b79764..c58eb593f6 100644 --- a/substrate/srml/staking/src/lib.rs +++ b/substrate/srml/staking/src/lib.rs @@ -15,17 +15,20 @@ // along with Substrate. If not, see . //! # Staking Module -//! +//! +//! The Staking module is used to manage funds at stake by network maintainers. +//! +//! - [`staking::Trait`](./trait.Trait.html) +//! - [`Call`](./enum.Call.html) +//! - [`Module`](./struct.Module.html) +//! +//! ## Overview //! //! The Staking module is the means by which a set of network maintainers (known as _authorities_ in some contexts //! and _validators_ in others) are chosen based upon those who voluntarily place funds under deposit. Under deposit, //! those funds are rewarded under normal operation but are held at pain of _slash_ (expropriation) should the //! staked maintainer be found not to be discharging its duties properly. //! -//! To use the Staking module in your runtime, you need to implement the [`staking::Trait`](./trait.Trait.html). -//! -//! ## Overview -//! //! ### Terminology //! //! @@ -118,12 +121,9 @@ //! The dispatchable functions of the Staking module enable the steps needed for entities to accept and change their //! role, alongside some helper functions to get/set the metadata of the module. //! -//! See the [`Call`](./enum.Call.html) enum and its associated variants for details of each function. -//! //! ### Public Functions //! -//! The Staking module contains many public storage items and (im)mutable functions. Please refer to the -//! [struct list](#structs) below and the [`Module`](./struct.Module.html) struct definition for more details. +//! The Staking module contains many public storage items and (im)mutable functions. //! //! ## Usage //! @@ -260,15 +260,13 @@ //! //! ## GenesisConfig //! -//! The Staking module depends on the genesis configuration. See the [`GenesisConfig`](./struct.GenesisConfig.html) -//! struct for a list of attributes that can be provided. +//! The Staking module depends on the [`GenesisConfig`](./struct.GenesisConfig.html). //! //! ## Related Modules //! -//! - [**Balances**](../srml_balances/index.html): Used to manage values at stake. -//! - [**Session**](../srml_session/index.html): Used to manage sessions. Also, a list of new validators is +//! - [Balances](../srml_balances/index.html): Used to manage values at stake. +//! - [Session](../srml_session/index.html): Used to manage sessions. Also, a list of new validators is //! stored in the Session module's `Validators` at the end of each era. -//! - [**System**](../srml_system/index.html): Used to obtain block number and time, among other details. #![cfg_attr(not(feature = "std"), no_std)] diff --git a/substrate/srml/sudo/src/lib.rs b/substrate/srml/sudo/src/lib.rs index 1d2e007820..8c59536469 100644 --- a/substrate/srml/sudo/src/lib.rs +++ b/substrate/srml/sudo/src/lib.rs @@ -16,6 +16,9 @@ //! # Sudo Module //! +//! - [`sudo::Trait`](./trait.Trait.html) +//! - [`Call`](./enum.Call.html) +//! //! ## Overview //! //! The Sudo module allows for a single account (called the "sudo key") @@ -23,8 +26,6 @@ //! or designate a new account to replace them as the sudo key. //! Only one account can be the sudo key at a time. //! -//! You can start using the Sudo module by implementing the [`sudo::Trait`](./trait.Trait.html). -//! //! ## Interface //! //! ### Dispatchable Functions @@ -34,27 +35,8 @@ //! * `sudo` - Make a `Root` call to a dispatchable function. //! * `set_key` - Assign a new account to be the sudo key. //! -//! See the [`Call`](./enum.Call.html) enum and its associated variants for details of each function. -//! //! ## Usage //! -//! ### Prerequisites -//! -//! To use the Sudo module in your runtime, you must implement the following trait in your runtime: -//! -//! ```ignore -//! impl sudo::Trait for Runtime { -//! type Event = Event; -//! type Proposal = Call; -//! } -//! ``` -//! -//! You can then import the Sudo module in your `construct_runtime!` macro with: -//! -//! ```ignore -//! Sudo: sudo, -//! ``` -//! //! ### Executing Privileged Functions //! //! The Sudo module itself is not intended to be used within other modules. @@ -68,8 +50,8 @@ //! //! This is an example of a module that exposes a privileged function: //! -//! ```ignore -//! use support::{decl_module, dispatch::Result}; +//! ``` +//! use srml_support::{decl_module, dispatch::Result}; //! use system::ensure_root; //! //! pub trait Trait: system::Trait {} @@ -85,18 +67,7 @@ //! } //! } //! } -//! ``` -//! -//! ### Example from SRML -//! -//! The Consensus module exposes a `set_code` privileged function -//! that allows you to set the on-chain Wasm runtime code: -//! -//! ```ignore -//! /// Set the new code. -//! pub fn set_code(new: Vec) { -//! storage::unhashed::put_raw(well_known_keys::CODE, &new); -//! } +//! # fn main() {} //! ``` //! //! ## Genesis Config @@ -104,14 +75,6 @@ //! The Sudo module depends on the [`GenesisConfig`](./struct.GenesisConfig.html). //! You need to set an initial superuser account as the sudo `key`. //! -//! ```ignore -//! GenesisConfig { -//! sudo: Some(SudoConfig { -//! key: AccountId, -//! }) -//! } -//! ``` -//! //! ## Related Modules //! //! * [Consensus](../srml_consensus/index.html) diff --git a/substrate/srml/system/src/lib.rs b/substrate/srml/system/src/lib.rs index 72a8636156..c410afd9ce 100644 --- a/substrate/srml/system/src/lib.rs +++ b/substrate/srml/system/src/lib.rs @@ -18,7 +18,8 @@ //! //! 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 need to implement the [`system::Trait`](./trait.Trait.html). +//! +//! - [`system::Trait`](./trait.Trait.html) //! //! ## Overview //! diff --git a/substrate/srml/timestamp/src/lib.rs b/substrate/srml/timestamp/src/lib.rs index 71fe2aed3f..9b72a1ac9b 100644 --- a/substrate/srml/timestamp/src/lib.rs +++ b/substrate/srml/timestamp/src/lib.rs @@ -17,8 +17,10 @@ //! # Timestamp Module //! //! The Timestamp module provides functionality to get and set the on-chain time. -//! To use it in your runtime, you need to implement the [`timestamp::Trait`](./trait.Trait.html). -//! Dispatchable functions are documented as part of the [`Call`](./enum.Call.html) enum. +//! +//! - [`timestamp::Trait`](./trait.Trait.html) +//! - [`Call`](./enum.Call.html) +//! - [`Module`](./struct.Module.html) //! //! ## Overview //! @@ -38,16 +40,12 @@ //! //! * `set` - Sets the current time. //! -//! See the [`Call`](./enum.Call.html) enum and its associated variants for details of each function. -//! //! ### Public functions //! //! * `get` - Gets the current time for the current block. If this function is called prior to //! setting the timestamp, it will return the timestamp of the previous block. //! * `minimum_period` - Gets the minimum (and advised) period between blocks for the chain. //! -//! See the [`Module`](./struct.Module.html) struct for details of publicly available functions. -//! //! ## Usage //! //! The following example shows how to use the Timestamp module in your custom module to query the current timestamp. @@ -83,8 +81,7 @@ //! //! ## Related Modules //! -//! * [`System`](../srml_system/index.html) -//! * [`Session`](../srml_session/index.html) +//! * [Session](../srml_session/index.html) #![cfg_attr(not(feature = "std"), no_std)]