From a2857011637a1f1e79fe069d5a2ca786c94d39cd Mon Sep 17 00:00:00 2001 From: Denis Pisarev Date: Thu, 5 Nov 2020 19:18:55 +0100 Subject: [PATCH] CI: markdown link checker (#7145) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * change (CI): markdown link checker * Fix some invalid doc links (re-run of cargo-unleash gen-readme w/ fixes). * Fix some invalid doc links * Fix some invalid doc links * Fix some links * Fix some links * Apply @bkchr suggestions from code review Co-authored-by: Bastian Köcher * Fix more links * Fix more links * typo * Fix more links * Fix more links * Ignore valid link .. check wrongly sees it as invalid * Fix style issue * Fix style issue * change (CI): update style guide link * change (lib): suggestions Co-authored-by: Dan Forbes Co-authored-by: Steve Degosserie Co-authored-by: Bastian Köcher --- .github/workflows/md-link-check.yml | 19 +++++++++ .github/workflows/mlc_config.json | 7 ++++ .maintain/chaostest/README.md | 7 ++-- .maintain/gitlab/check_line_width.sh | 4 +- README.md | 2 +- bin/node-template/README.md | 2 +- client/block-builder/README.md | 2 +- client/block-builder/src/lib.rs | 2 +- client/chain-spec/README.md | 2 +- client/chain-spec/src/lib.rs | 2 +- client/consensus/babe/README.md | 2 +- client/consensus/babe/src/lib.rs | 2 +- docs/PULL_REQUEST_TEMPLATE.md | 2 +- docs/SECURITY.md | 1 + frame/balances/README.md | 2 +- frame/balances/src/lib.rs | 2 +- frame/benchmarking/README.md | 2 +- frame/example-offchain-worker/README.md | 7 ++-- frame/example-offchain-worker/src/lib.rs | 1 + frame/example/README.md | 1 + frame/example/src/lib.rs | 1 + frame/society/README.md | 2 +- frame/staking/README.md | 20 ++++----- frame/staking/src/lib.rs | 2 +- frame/timestamp/README.md | 8 ++-- primitives/allocator/README.md | 2 +- primitives/api/README.md | 4 +- primitives/npos-elections/README.md | 53 ++++++++++++++++++++++-- primitives/runtime-interface/README.md | 29 ++++++------- primitives/runtime-interface/src/lib.rs | 23 +++++----- 30 files changed, 148 insertions(+), 67 deletions(-) create mode 100644 .github/workflows/md-link-check.yml create mode 100644 .github/workflows/mlc_config.json diff --git a/.github/workflows/md-link-check.yml b/.github/workflows/md-link-check.yml new file mode 100644 index 0000000000000..75948534b3c19 --- /dev/null +++ b/.github/workflows/md-link-check.yml @@ -0,0 +1,19 @@ +name: Check Links + +on: + pull_request: + branches: + - master + push: + branches: + - master + +jobs: + markdown-link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: 'yes' + config-file: '.github/workflows/mlc_config.json' diff --git a/.github/workflows/mlc_config.json b/.github/workflows/mlc_config.json new file mode 100644 index 0000000000000..f741e987b1b2a --- /dev/null +++ b/.github/workflows/mlc_config.json @@ -0,0 +1,7 @@ +{ + "ignorePatterns": [ + { + "pattern": "^https://crates.io" + } + ] +} diff --git a/.maintain/chaostest/README.md b/.maintain/chaostest/README.md index dc3d07b57905e..60342e15b7d58 100644 --- a/.maintain/chaostest/README.md +++ b/.maintain/chaostest/README.md @@ -1,3 +1,4 @@ + chaostest ========= @@ -56,7 +57,7 @@ DESCRIPTION Extra documentation goes here ``` -_See code: [src/commands/spawn/index.js](https://github.com/paritytech/substrate/blob/harry/chaostest-init/.maintain/chaostest/src/commands/spawn/index.js)_ +_See code: [src/commands/spawn/index.js](https://github.com/paritytech/substrate/blob/master/.maintain/chaostest/src/commands/spawn/index.js)_ ## `chaostest singlenodeheight` @@ -71,7 +72,7 @@ FLAGS -t, the wait time out before it halts the polling ``` -_See code: [src/commands/singlenodeheight/index.js](https://github.com/paritytech/substrate/blob/harry/chaostest-init/.maintain/chaostest/src/commands/singlenodeheight/index.js)_ +_See code: [src/commands/singlenodeheight/index.js](https://github.com/paritytech/substrate/blob/master/.maintain/chaostest/src/commands/singlenodeheight/index.js)_ ## `chaostest clean` @@ -85,5 +86,5 @@ FLAGS -n , the desired namespace to delete on your k8s cluster ``` -_See code: [src/commands/clean/index.js](https://github.com/paritytech/substrate/blob/harry/chaostest-init/.maintain/chaostest/src/commands/clean/index.js)_ +_See code: [src/commands/clean/index.js](https://github.com/paritytech/substrate/blob/master/.maintain/chaostest/src/commands/clean/index.js)_ diff --git a/.maintain/gitlab/check_line_width.sh b/.maintain/gitlab/check_line_width.sh index 611d3ae2681e2..ebab3013e4b48 100755 --- a/.maintain/gitlab/check_line_width.sh +++ b/.maintain/gitlab/check_line_width.sh @@ -25,7 +25,7 @@ do echo "| error!" echo "| Lines must not be longer than ${LINE_WIDTH} characters." echo "| " - echo "| see more https://wiki.parity.io/Substrate-Style-Guide" + echo "| see more https://github.com/paritytech/substrate/blob/master/docs/STYLE_GUIDE.md" echo "|" FAIL="true" fi @@ -41,7 +41,7 @@ do echo "| warning!" echo "| Lines should be longer than ${GOOD_LINE_WIDTH} characters only in exceptional circumstances!" echo "| " - echo "| see more https://wiki.parity.io/Substrate-Style-Guide" + echo "| see more https://github.com/paritytech/substrate/blob/master/docs/STYLE_GUIDE.md" echo "|" fi echo "| file: ${file}" diff --git a/README.md b/README.md index c586919a1ddc3..94de8533be266 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Substrate · [![GitHub license](https://img.shields.io/badge/license-GPL3%2FApache2-blue)](LICENSE) [![GitLab Status](https://gitlab.parity.io/parity/substrate/badges/master/pipeline.svg)](https://gitlab.parity.io/parity/substrate/pipelines) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/CONTRIBUTING.adoc) +# Substrate · [![GitHub license](https://img.shields.io/badge/license-GPL3%2FApache2-blue)](#LICENSE) [![GitLab Status](https://gitlab.parity.io/parity/substrate/badges/master/pipeline.svg)](https://gitlab.parity.io/parity/substrate/pipelines) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/CONTRIBUTING.adoc)

diff --git a/bin/node-template/README.md b/bin/node-template/README.md index 5623fedb5342b..c1aeefe895095 100644 --- a/bin/node-template/README.md +++ b/bin/node-template/README.md @@ -55,7 +55,7 @@ RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/node-template -lruntime=debug - ### Multi-Node Local Testnet To see the multi-node consensus algorithm in action, run a local testnet with two validator nodes, -Alice and Bob, that have been [configured](/bin/node-template/node/src/chain_spec.rs) as the initial +Alice and Bob, that have been [configured](./node/src/chain_spec.rs) as the initial authorities of the `local` testnet chain and endowed with testnet units. Note: this will require two terminal sessions (one for each node). diff --git a/client/block-builder/README.md b/client/block-builder/README.md index c691f6692abff..b105d4203362f 100644 --- a/client/block-builder/README.md +++ b/client/block-builder/README.md @@ -1,7 +1,7 @@ Substrate block builder This crate provides the [`BlockBuilder`] utility and the corresponding runtime api -[`BlockBuilder`](sp_block_builder::BlockBuilder).Error +[`BlockBuilder`](https://docs.rs/sc-block-builder/latest/sc_block_builder/struct.BlockBuilder.html).Error The block builder utility is used in the node as an abstraction over the runtime api to initialize a block, to push extrinsics and to finalize a block. diff --git a/client/block-builder/src/lib.rs b/client/block-builder/src/lib.rs index 904667b1afc6e..8a38bb8478003 100644 --- a/client/block-builder/src/lib.rs +++ b/client/block-builder/src/lib.rs @@ -19,7 +19,7 @@ //! Substrate block builder //! //! This crate provides the [`BlockBuilder`] utility and the corresponding runtime api -//! [`BlockBuilder`](sp_block_builder::BlockBuilder).Error +//! [`BlockBuilder`](sp_block_builder::BlockBuilder). //! //! The block builder utility is used in the node as an abstraction over the runtime api to //! initialize a block, to push extrinsics and to finalize a block. diff --git a/client/chain-spec/README.md b/client/chain-spec/README.md index 59a66aa5ace79..5525affbed81c 100644 --- a/client/chain-spec/README.md +++ b/client/chain-spec/README.md @@ -4,7 +4,7 @@ This crate contains structs and utilities to declare a runtime-specific configuration file (a.k.a chain spec). Basic chain spec type containing all required parameters is -[`ChainSpec`](https://docs.rs/sc-chain-spec/latest/sc_chain_spec/struct.ChainSpec.html). It can be extended with +[`ChainSpec`](https://docs.rs/sc-chain-spec/latest/sc_chain_spec/struct.GenericChainSpec.html). It can be extended with additional options that contain configuration specific to your chain. Usually the extension is going to be an amalgamate of types exposed by Substrate core modules. To allow the core modules to retrieve diff --git a/client/chain-spec/src/lib.rs b/client/chain-spec/src/lib.rs index 94ed93758bb2d..27657ccb7f869 100644 --- a/client/chain-spec/src/lib.rs +++ b/client/chain-spec/src/lib.rs @@ -20,7 +20,7 @@ //! a runtime-specific configuration file (a.k.a chain spec). //! //! Basic chain spec type containing all required parameters is -//! [`ChainSpec`](./struct.ChainSpec.html). It can be extended with +//! [`GenericChainSpec`]. It can be extended with //! additional options that contain configuration specific to your chain. //! Usually the extension is going to be an amalgamate of types exposed //! by Substrate core modules. To allow the core modules to retrieve diff --git a/client/consensus/babe/README.md b/client/consensus/babe/README.md index faba3948ed715..a404d2ea44706 100644 --- a/client/consensus/babe/README.md +++ b/client/consensus/babe/README.md @@ -43,6 +43,6 @@ primary blocks in the chain. We will pick the heaviest chain (more primary blocks) and will go with the longest one in case of a tie. An in-depth description and analysis of the protocol can be found here: - + License: GPL-3.0-or-later WITH Classpath-exception-2.0 \ No newline at end of file diff --git a/client/consensus/babe/src/lib.rs b/client/consensus/babe/src/lib.rs index e980e358b848d..948959e96495c 100644 --- a/client/consensus/babe/src/lib.rs +++ b/client/consensus/babe/src/lib.rs @@ -59,7 +59,7 @@ //! blocks) and will go with the longest one in case of a tie. //! //! An in-depth description and analysis of the protocol can be found here: -//! +//! #![forbid(unsafe_code)] #![warn(missing_docs)] diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md index 8ca6ba9b01fe2..77f5f79f60d40 100644 --- a/docs/PULL_REQUEST_TEMPLATE.md +++ b/docs/PULL_REQUEST_TEMPLATE.md @@ -14,7 +14,7 @@ Before you submitting, please check that: - [ ] Github's project assignment - [ ] You mentioned a related issue if this PR related to it, e.g. `Fixes #228` or `Related #1337`. - [ ] You asked any particular reviewers to review. If you aren't sure, start with GH suggestions. -- [ ] Your PR adheres to [the style guide](https://wiki.parity.io/Substrate-Style-Guide) +- [ ] Your PR adheres to [the style guide](https://github.com/paritytech/substrate/blob/master/docs/STYLE_GUIDE.md) - In particular, mind the maximal line length of 100 (120 in exceptional circumstances). - There is no commented code checked in unless necessary. - Any panickers have a proof or removed. diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 7240218fa8729..19f5b145feb5e 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -1,3 +1,4 @@ + # Security Policy Parity Technologies is committed to resolving security vulnerabilities in our software quickly and carefully. We take the necessary steps to minimize risk, provide timely information, and deliver vulnerability fixes and mitigations required to address security issues. diff --git a/frame/balances/README.md b/frame/balances/README.md index 4104fdc641975..a93ed5f306e0f 100644 --- a/frame/balances/README.md +++ b/frame/balances/README.md @@ -62,7 +62,7 @@ dealing with accounts that allow liquidity restrictions. - [`Imbalance`](https://docs.rs/frame-support/latest/frame_support/traits/trait.Imbalance.html): Functions for handling imbalances between total issuance in the system and account balances. Must be used when a function creates new funds (e.g. a reward) or destroys some funds (e.g. a system fee). -- [`IsDeadAccount`](https://docs.rs/frame-system/latest/frame_system/trait.IsDeadAccount.html): Determiner to say whether a +- [`IsDeadAccount`](https://docs.rs/frame-support/latest/frame_support/traits/trait.IsDeadAccount.html): Determiner to say whether a given account is unused. ## Interface diff --git a/frame/balances/src/lib.rs b/frame/balances/src/lib.rs index 6c9d3adfedaa7..7ca6fd1e78091 100644 --- a/frame/balances/src/lib.rs +++ b/frame/balances/src/lib.rs @@ -79,7 +79,7 @@ //! - [`Imbalance`](../frame_support/traits/trait.Imbalance.html): Functions for handling //! imbalances between total issuance in the system and account balances. Must be used when a function //! creates new funds (e.g. a reward) or destroys some funds (e.g. a system fee). -//! - [`IsDeadAccount`](../frame_system/trait.IsDeadAccount.html): Determiner to say whether a +//! - [`IsDeadAccount`](../frame_support/traits/trait.IsDeadAccount.html): Determiner to say whether a //! given account is unused. //! //! ## Interface diff --git a/frame/benchmarking/README.md b/frame/benchmarking/README.md index 1727072709b21..38c683cb8db5b 100644 --- a/frame/benchmarking/README.md +++ b/frame/benchmarking/README.md @@ -43,7 +43,7 @@ The benchmarking framework comes with the following tools: * [A set of macros](./src/lib.rs) (`benchmarks!`, `add_benchmark!`, etc...) to make it easy to write, test, and add runtime benchmarks. * [A set of linear regression analysis functions](./src/analysis.rs) for processing benchmark data. -* [A CLI extension](../../utils/benchmarking-cli/) to make it easy to execute benchmarks on your +* [A CLI extension](../../utils/frame/benchmarking-cli/) to make it easy to execute benchmarks on your node. The end-to-end benchmarking pipeline is disabled by default when compiling a node. If you want to diff --git a/frame/example-offchain-worker/README.md b/frame/example-offchain-worker/README.md index 4da1a4c15f814..a2a95a8cfb97e 100644 --- a/frame/example-offchain-worker/README.md +++ b/frame/example-offchain-worker/README.md @@ -1,3 +1,4 @@ + # Offchain Worker Example Module The Offchain Worker Example: A simple pallet demonstrating @@ -6,9 +7,9 @@ concepts, APIs and structures common to most offchain workers. Run `cargo doc --package pallet-example-offchain-worker --open` to view this module's documentation. -- [`pallet_example_offchain_worker::Trait`](https://docs.rs/pallet-example-offchain-worker/latest/pallet_example_offchain_worker/trait.Trait.html) -- [`Call`](https://docs.rs/pallet-example-offchain-worker/latest/pallet_example_offchain_worker/enum.Call.html) -- [`Module`](https://docs.rs/pallet-example-offchain-worker/latest/pallet_example_offchain_worker/struct.Module.html) +- [`pallet_example_offchain_worker::Trait`](./trait.Trait.html) +- [`Call`](./enum.Call.html) +- [`Module`](./struct.Module.html) ## Overview diff --git a/frame/example-offchain-worker/src/lib.rs b/frame/example-offchain-worker/src/lib.rs index 5fd5eff19bd73..b64e3f8dd83f5 100644 --- a/frame/example-offchain-worker/src/lib.rs +++ b/frame/example-offchain-worker/src/lib.rs @@ -15,6 +15,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! //! # Offchain Worker Example Module //! //! The Offchain Worker Example: A simple pallet demonstrating diff --git a/frame/example/README.md b/frame/example/README.md index 05ef4cd4351cf..f1435a297b09e 100644 --- a/frame/example/README.md +++ b/frame/example/README.md @@ -1,3 +1,4 @@ + # Example Pallet diff --git a/frame/example/src/lib.rs b/frame/example/src/lib.rs index 4b10804fb10f7..103bcfe696868 100644 --- a/frame/example/src/lib.rs +++ b/frame/example/src/lib.rs @@ -15,6 +15,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! //! # Example Pallet //! //! diff --git a/frame/society/README.md b/frame/society/README.md index b4e1fbaf22cba..372dfe1f048ef 100644 --- a/frame/society/README.md +++ b/frame/society/README.md @@ -24,7 +24,7 @@ Of the non-suspended members, there is always a: Of the non-suspended members of the society, a random set of them are chosen as "skeptics". The mechanics of skeptics is explained in the -[member phase](#member-phase) below. +[member phase](https://docs.rs/pallet-society/latest/pallet_society/#member-phase) below. ### Mechanics diff --git a/frame/staking/README.md b/frame/staking/README.md index b7b2141e58a5b..78474ee842216 100644 --- a/frame/staking/README.md +++ b/frame/staking/README.md @@ -57,7 +57,7 @@ There are three possible roles that any staked account pair can be in: `Validato and `Idle` (defined in [`StakerStatus`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.StakerStatus.html)). There are three corresponding instructions to change between roles, namely: [`validate`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.validate), -[`nominate`](./enum.Call.html#variant.nominate), and [`chill`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.chill). +[`nominate`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.nominate), and [`chill`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.chill). #### Validating @@ -81,7 +81,7 @@ between the validator and its nominators. This rule incentivizes the nominators the misbehaving/offline validators as much as possible, simply because the nominators will also lose funds if they vote poorly. -An account can become a nominator via the [`nominate`](enum.Call.html#variant.nominate) call. +An account can become a nominator via the [`nominate`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.nominate) call. #### Rewards and Slash @@ -102,7 +102,7 @@ Slashing logic is further described in the documentation of the `slashing` modul Similar to slashing, rewards are also shared among a validator and its associated nominators. Yet, the reward funds are not always transferred to the stash account and can be configured. See -[Reward Calculation](#reward-calculation) for more details. +[Reward Calculation](https://docs.rs/pallet-staking/latest/pallet_staking/#reward-calculation) for more details. #### Chilling @@ -110,7 +110,7 @@ Finally, any of the roles above can choose to step back temporarily and just chi This means that if they are a nominator, they will not be considered as voters anymore and if they are validators, they will no longer be a candidate for the next election. -An account can step back via the [`chill`](enum.Call.html#variant.chill) call. +An account can step back via the [`chill`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.chill) call. ### Session managing @@ -183,7 +183,7 @@ they received during the era. Points are added to a validator using [`reward_by_ids`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.reward_by_ids) or [`reward_by_indices`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.reward_by_indices). -[`Module`](./struct.Module.html) implements +[`Module`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Module.html) implements [`pallet_authorship::EventHandler`](https://docs.rs/pallet-authorship/latest/pallet_authorship/trait.EventHandler.html) to add reward points to block producer and block producer of referenced uncles. @@ -198,11 +198,11 @@ validator and all of the nominators that nominated the validator, proportional t staked behind this validator (_i.e._ dividing the [`own`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Exposure.html#structfield.own) or [`others`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Exposure.html#structfield.others) by -[`total`](./struct.Exposure.html#structfield.total) in [`Exposure`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Exposure.html)). +[`total`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Exposure.html#structfield.total) in [`Exposure`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Exposure.html)). All entities who receive a reward have the option to choose their reward destination through the [`Payee`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.Payee.html) storage item (see -[`set_payee`](enum.Call.html#variant.set_payee)), to be one of the following: +[`set_payee`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.set_payee)), to be one of the following: - Controller account, (obviously) not increasing the staked value. - Stash account, not increasing the staked value. @@ -213,14 +213,14 @@ All entities who receive a reward have the option to choose their reward destina Any funds already placed into stash can be the target of the following operations: The controller account can free a portion (or all) of the funds using the -[`unbond`](enum.Call.html#variant.unbond) call. Note that the funds are not immediately -accessible. Instead, a duration denoted by [`BondingDuration`](https://docs.rs/pallet-staking/latest/pallet_staking/struct.BondingDuration.html) +[`unbond`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.unbond) call. Note that the funds are not immediately +accessible. Instead, a duration denoted by [`BondingDuration`](https://docs.rs/pallet-staking/latest/pallet_staking/trait.Trait.html#associatedtype.BondingDuration) (in number of eras) must pass until the funds can actually be removed. Once the `BondingDuration` is over, the [`withdraw_unbonded`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.withdraw_unbonded) call can be used to actually withdraw the funds. Note that there is a limitation to the number of fund-chunks that can be scheduled to be -unlocked in the future via [`unbond`](enum.Call.html#variant.unbond). In case this maximum +unlocked in the future via [`unbond`](https://docs.rs/pallet-staking/latest/pallet_staking/enum.Call.html#variant.unbond). In case this maximum (`MAX_UNLOCKING_CHUNKS`) is reached, the bonded account _must_ first wait until a successful call to `withdraw_unbonded` to remove some of the chunks. diff --git a/frame/staking/src/lib.rs b/frame/staking/src/lib.rs index fdea1c18e768b..e5aaae6bbb8f9 100644 --- a/frame/staking/src/lib.rs +++ b/frame/staking/src/lib.rs @@ -232,7 +232,7 @@ //! //! The controller account can free a portion (or all) of the funds using the //! [`unbond`](enum.Call.html#variant.unbond) call. Note that the funds are not immediately -//! accessible. Instead, a duration denoted by [`BondingDuration`](./struct.BondingDuration.html) +//! accessible. Instead, a duration denoted by [`BondingDuration`](./trait.Trait.html#associatedtype.BondingDuration) //! (in number of eras) must pass until the funds can actually be removed. Once the //! `BondingDuration` is over, the [`withdraw_unbonded`](./enum.Call.html#variant.withdraw_unbonded) //! call can be used to actually withdraw the funds. diff --git a/frame/timestamp/README.md b/frame/timestamp/README.md index 5610caca4da51..54ef7fa43b4f0 100644 --- a/frame/timestamp/README.md +++ b/frame/timestamp/README.md @@ -2,9 +2,9 @@ The Timestamp module provides functionality to get and set the on-chain time. -- [`timestamp::Trait`](https://docs.rs/pallet-timestamppallet-timestamp/latest/pallet_timestamp/trait.Trait.html) -- [`Call`](https://docs.rs/pallet-timestamppallet-timestamp/latest/pallet_timestamp/enum.Call.html) -- [`Module`](https://docs.rs/pallet-timestamppallet-timestamp/latest/pallet_timestamp/struct.Module.html) +- [`timestamp::Trait`](https://docs.rs/pallet-timestamp/latest/pallet_timestamp/trait.Trait.html) +- [`Call`](https://docs.rs/pallet-timestamp/latest/pallet_timestamp/enum.Call.html) +- [`Module`](https://docs.rs/pallet-timestamp/latest/pallet_timestamp/struct.Module.html) ## Overview @@ -69,6 +69,6 @@ the Timestamp module for session management. ## Related Modules -* [Session](https://docs.rs/pallet-timestamppallet-session/latest/pallet_session/) +* [Session](https://docs.rs/pallet-session/latest/pallet_session/) License: Apache-2.0 \ No newline at end of file diff --git a/primitives/allocator/README.md b/primitives/allocator/README.md index 361feaae591f9..cd845e2b028eb 100644 --- a/primitives/allocator/README.md +++ b/primitives/allocator/README.md @@ -1,6 +1,6 @@ Collection of allocator implementations. This crate provides the following allocator implementations: -- A freeing-bump allocator: [`FreeingBumpHeapAllocator`](freeing_bump::FreeingBumpHeapAllocator) +- A freeing-bump allocator: [`FreeingBumpHeapAllocator`](https://docs.rs/sp-allocator/latest/sp_allocator/struct.FreeingBumpHeapAllocator.html) License: Apache-2.0 \ No newline at end of file diff --git a/primitives/api/README.md b/primitives/api/README.md index 551de2f82e365..1cf9437373c77 100644 --- a/primitives/api/README.md +++ b/primitives/api/README.md @@ -3,8 +3,8 @@ Substrate runtime api The Substrate runtime api is the crucial interface between the node and the runtime. Every call that goes into the runtime is done with a runtime api. The runtime apis are not fixed. Every Substrate user can define its own apis with -[`decl_runtime_apis`](macro.decl_runtime_apis.html) and implement them in -the runtime with [`impl_runtime_apis`](macro.impl_runtime_apis.html). +[`decl_runtime_apis`](https://docs.rs/sp-api/latest/sp_api/macro.decl_runtime_apis.html) and implement them in +the runtime with [`impl_runtime_apis`](https://docs.rs/sp-api/latest/sp_api/macro.impl_runtime_apis.html). Every Substrate runtime needs to implement the [`Core`] runtime api. This api provides the basic functionality that every runtime needs to export. diff --git a/primitives/npos-elections/README.md b/primitives/npos-elections/README.md index a98351a6d89a7..b518e63615fa6 100644 --- a/primitives/npos-elections/README.md +++ b/primitives/npos-elections/README.md @@ -1,11 +1,58 @@ A set of election algorithms to be used with a substrate runtime, typically within the staking -sub-system. Notable implementation include +sub-system. Notable implementation include: - [`seq_phragmen`]: Implements the Phragmén Sequential Method. An un-ranked, relatively fast election method that ensures PJR, but does not provide a constant factor approximation of the maximin problem. -- [`balance_solution`]: Implements the star balancing algorithm. This iterative process can - increase a solutions score, as described in [`evaluate_support`]. +- [`phragmms`]: Implements a hybrid approach inspired by Phragmén which is executed faster but + it can achieve a constant factor approximation of the maximin problem, similar to that of the + MMS algorithm. +- [`balance_solution`]: Implements the star balancing algorithm. This iterative process can push + a solution toward being more `balances`, which in turn can increase its score. + +### Terminology + +This crate uses context-independent words, not to be confused with staking. This is because the +election algorithms of this crate, while designed for staking, can be used in other contexts as +well. + +`Voter`: The entity casting some votes to a number of `Targets`. This is the same as `Nominator` +in the context of staking. `Target`: The entities eligible to be voted upon. This is the same as +`Validator` in the context of staking. `Edge`: A mapping from a `Voter` to a `Target`. + +The goal of an election algorithm is to provide an `ElectionResult`. A data composed of: +- `winners`: A flat list of identifiers belonging to those who have won the election, usually + ordered in some meaningful way. They are zipped with their total backing stake. +- `assignment`: A mapping from each voter to their winner-only targets, zipped with a ration + denoting the amount of support given to that particular target. + +```rust +// the winners. +let winners = vec![(1, 100), (2, 50)]; +let assignments = vec![ + // A voter, giving equal backing to both 1 and 2. + Assignment { + who: 10, + distribution: vec![(1, Perbill::from_percent(50)), (2, Perbill::from_percent(50))], + }, + // A voter, Only backing 1. + Assignment { who: 20, distribution: vec![(1, Perbill::from_percent(100))] }, +]; + +// the combination of the two makes the election result. +let election_result = ElectionResult { winners, assignments }; + +``` + +The `Assignment` field of the election result is voter-major, i.e. it is from the perspective of +the voter. The struct that represents the opposite is called a `Support`. This struct is usually +accessed in a map-like manner, i.e. keyed vy voters, therefor it is stored as a mapping called +`SupportMap`. + +Moreover, the support is built from absolute backing values, not ratios like the example above. +A struct similar to `Assignment` that has stake value instead of ratios is called an +`StakedAssignment`. + More information can be found at: https://arxiv.org/abs/2004.12990 diff --git a/primitives/runtime-interface/README.md b/primitives/runtime-interface/README.md index 666bfe4d5a861..49e13f1b2e743 100644 --- a/primitives/runtime-interface/README.md +++ b/primitives/runtime-interface/README.md @@ -7,18 +7,19 @@ maps to an external function call. These external functions are exported by the and they map to the same implementation as the native calls. # Using a type in a runtime interface - + Any type that should be used in a runtime interface as argument or return value needs to -implement [`RIType`]. The associated type [`FFIType`](RIType::FFIType) is the type that is used -in the FFI function to represent the actual type. For example `[T]` is represented by an `u64`. -The slice pointer and the length will be mapped to an `u64` value. For more information see -this [table](#ffi-type-and-conversion). The FFI function definition is used when calling from -the wasm runtime into the node. - -Traits are used to convert from a type to the corresponding [`RIType::FFIType`]. +implement [`RIType`]. The associated type [`FFIType`](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/trait.RIType.html#associatedtype.FFIType) +is the type that is used in the FFI function to represent the actual type. For example `[T]` is +represented by an `u64`. The slice pointer and the length will be mapped to an `u64` value. +For more information see this [table](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/#ffi-type-and-conversion). +The FFI function definition is used when calling from the wasm runtime into the node. + +Traits are used to convert from a type to the corresponding +[`RIType::FFIType`](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/trait.RIType.html#associatedtype.FFIType). Depending on where and how a type should be used in a function signature, a combination of the following traits need to be implemented: - + 1. Pass as function argument: [`wasm::IntoFFIValue`] and [`host::FromFFIValue`] 2. As function return value: [`wasm::FromFFIValue`] and [`host::IntoFFIValue`] 3. Pass as mutable function argument: [`host::IntoPreallocatedFFIValue`] @@ -26,7 +27,7 @@ following traits need to be implemented: The traits are implemented for most of the common types like `[T]`, `Vec`, arrays and primitive types. -For custom types, we provide the [`PassBy`](pass_by::PassBy) trait and strategies that define +For custom types, we provide the [`PassBy`](https://docs.rs/sp-runtime-interface/latest/sp_runtime_interface/pass_by#PassBy) trait and strategies that define how a type is passed between the wasm runtime and the node. Each strategy also provides a derive macro to simplify the implementation. @@ -52,7 +53,7 @@ trait RuntimeInterface { ``` For more information on declaring a runtime interface, see -[`#[runtime_interface]`](attr.runtime_interface.html). +[`#[runtime_interface]`](https://docs.rs/sp-runtime-interface/latest/sp_runtime_interface/attr.runtime_interface.html). # FFI type and conversion @@ -80,9 +81,9 @@ the host side and how they are converted into the corresponding type. | `[u8; N]` | `u32` | `v.as_ptr()` | | `*const T` | `u32` | `Identity` | | `Option` | `u64` | `let e = v.encode();`

e.len() 32bit << 32 | e.as_ptr() 32bit | -| [`T where T: PassBy`](pass_by::Inner) | Depends on inner | Depends on inner | -| [`T where T: PassBy`](pass_by::Codec) | `u64`| v.len() 32bit << 32 | v.as_ptr() 32bit | +| [`T where T: PassBy`](https://docs.rs/sp-runtime-interface/latest/sp_runtime_interface/pass_by#Inner) | Depends on inner | Depends on inner | +| [`T where T: PassBy`](https://docs.rs/sp-runtime-interface/latest/sp_runtime_interface/pass_by#Codec) | `u64`| v.len() 32bit << 32 | v.as_ptr() 32bit | `Identity` means that the value is converted directly into the corresponding FFI type. -License: Apache-2.0 \ No newline at end of file +License: Apache-2.0 diff --git a/primitives/runtime-interface/src/lib.rs b/primitives/runtime-interface/src/lib.rs index 7ff5f0d7a042d..dd625a4a25346 100644 --- a/primitives/runtime-interface/src/lib.rs +++ b/primitives/runtime-interface/src/lib.rs @@ -26,16 +26,17 @@ //! # Using a type in a runtime interface //! //! Any type that should be used in a runtime interface as argument or return value needs to -//! implement [`RIType`]. The associated type [`FFIType`](RIType::FFIType) is the type that is used -//! in the FFI function to represent the actual type. For example `[T]` is represented by an `u64`. -//! The slice pointer and the length will be mapped to an `u64` value. For more information see -//! this [table](#ffi-type-and-conversion). The FFI function definition is used when calling from -//! the wasm runtime into the node. +//! implement [`RIType`]. The associated type [`FFIType`](./trait.RIType.html#associatedtype.FFIType) +//! is the type that is used in the FFI function to represent the actual type. For example `[T]` is +//! represented by an `u64`. The slice pointer and the length will be mapped to an `u64` value. +//! For more information see this [table](#ffi-type-and-conversion). +//! The FFI function definition is used when calling from the wasm runtime into the node. //! -//! Traits are used to convert from a type to the corresponding [`RIType::FFIType`]. +//! Traits are used to convert from a type to the corresponding +//! [`RIType::FFIType`](./trait.RIType.html#associatedtype.FFIType). //! Depending on where and how a type should be used in a function signature, a combination of the //! following traits need to be implemented: -//! +//! //! 1. Pass as function argument: [`wasm::IntoFFIValue`] and [`host::FromFFIValue`] //! 2. As function return value: [`wasm::FromFFIValue`] and [`host::IntoFFIValue`] //! 3. Pass as mutable function argument: [`host::IntoPreallocatedFFIValue`] @@ -43,7 +44,7 @@ //! The traits are implemented for most of the common types like `[T]`, `Vec`, arrays and //! primitive types. //! -//! For custom types, we provide the [`PassBy`](pass_by::PassBy) trait and strategies that define +//! For custom types, we provide the [`PassBy`](./pass_by#PassBy) trait and strategies that define //! how a type is passed between the wasm runtime and the node. Each strategy also provides a derive //! macro to simplify the implementation. //! @@ -69,7 +70,7 @@ //! ``` //! //! For more information on declaring a runtime interface, see -//! [`#[runtime_interface]`](attr.runtime_interface.html). +//! [`#[runtime_interface]`](./attr.runtime_interface.html). //! //! # FFI type and conversion //! @@ -97,8 +98,8 @@ //! | `[u8; N]` | `u32` | `v.as_ptr()` | //! | `*const T` | `u32` | `Identity` | //! | `Option` | `u64` | `let e = v.encode();`

e.len() 32bit << 32 | e.as_ptr() 32bit | -//! | [`T where T: PassBy`](pass_by::Inner) | Depends on inner | Depends on inner | -//! | [`T where T: PassBy`](pass_by::Codec) | `u64`| v.len() 32bit << 32 | v.as_ptr() 32bit | +//! | [`T where T: PassBy`](./pass_by#Inner) | Depends on inner | Depends on inner | +//! | [`T where T:PassBy`](./pass_by#Codec)|`u64`|v.len() 32bit << 32 |v.as_ptr() 32bit| //! //! `Identity` means that the value is converted directly into the corresponding FFI type.