From eb7462b1d153f3373a281f14c17719c88375e82d Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 17:42:03 +0200 Subject: [PATCH 01/86] typo --- docs/sdk/src/meta_contributing.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/meta_contributing.rs b/docs/sdk/src/meta_contributing.rs index a029595254c8..e1297151b231 100644 --- a/docs/sdk/src/meta_contributing.rs +++ b/docs/sdk/src/meta_contributing.rs @@ -14,7 +14,7 @@ //! documentation up-to-date, as the overhead is reduced by making sure everything is in one //! repository, and everything being in `.rs` files. //! -//! > This is not say that a more visually appealing version of this crate (for example as an +//! > This is not to say that a more visually appealing version of this crate (for example as an //! > `md-book`) cannot exist, but it would be outside the scope of this crate. //! //! Moreover, we acknowledge that a major pain point has been not only outdated *concepts*, but also From 954c06af9459ca2a70ebdddc693178922734ef1f Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:06:58 +0200 Subject: [PATCH 02/86] formatting typo --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 96811a2772d7..647acae68b5b 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -88,7 +88,7 @@ sections](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/ru we will most likely not need to think about panic and safety in any runtime related code. Our code is never `unsafe`, and will (almost) never panic. -Use `# Examples as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free +Use `# Examples` as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free test coverage. As an additional benefit, any code in rust-docs is treated as an "integration tests", not unit tests, which tests your crate in a different way than unit tests. So, it is both a win for "more documentation" and a win for "more test coverage". From 8791ae5e0a62b3f2651885809c3cd224d869b13d Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:08:47 +0200 Subject: [PATCH 03/86] fix link --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 647acae68b5b..a824a2f45d38 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -33,7 +33,7 @@ First, consider the case for all such crates, except for those that are pallets. The first question is, what should you document? Use this filter: -1. In the crates assigned to `docs-audit` in [CODEOWNERS](./CODEOWNERS), +1. In the crates assigned to `docs-audit` in [CODEOWNERS](/.github/CODEOWNERS), 2. All `pub` items need to be documented. If not `pub`, it doesn't appear in the rust-docs, and is not public facing. - Within `pub` items, sometimes they are only `pub` to be used by another internal crate, and you can foresee that From 7519e51410f1ccbbd8cb9fb09cbd5fd51de1a84e Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:09:56 +0200 Subject: [PATCH 04/86] fix link --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index a824a2f45d38..3263dd647b97 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -1,7 +1,7 @@ # Substrate Documentation Guidelines This document is focused on documenting parts of Substrate that relate to its external API. The list of such crates can -be found in [CODEOWNERS](./CODEOWNERS). Search for the crates auto-assigned to the `docs-audit` team. +be found in [CODEOWNERS](/.github/CODEOWNERS). Search for the crates auto-assigned to the `docs-audit` team. These crates are used by external developers and need thorough documentation. They are the most concerned with FRAME development. From 4b9be0b3ce88faeba17776b493ae946528ae6827 Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:29:03 +0200 Subject: [PATCH 05/86] non-plural --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 3263dd647b97..b32a74020906 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -89,7 +89,7 @@ we will most likely not need to think about panic and safety in any runtime rela and will (almost) never panic. Use `# Examples` as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free -test coverage. As an additional benefit, any code in rust-docs is treated as an "integration tests", not unit tests, +test coverage. As an additional benefit, any code in rust-docs is treated as an "integration test", not unit test, which tests your crate in a different way than unit tests. So, it is both a win for "more documentation" and a win for "more test coverage". From 72a46ea1be78fade78fd6403f4ebaab298b537ea Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:29:39 +0200 Subject: [PATCH 06/86] repetition? --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index b32a74020906..063974615f90 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -89,7 +89,7 @@ we will most likely not need to think about panic and safety in any runtime rela and will (almost) never panic. Use `# Examples` as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free -test coverage. As an additional benefit, any code in rust-docs is treated as an "integration test", not unit test, +test coverage. As an additional benefit, any code in rust-docs is treated as an "integration test", which tests your crate in a different way than unit tests. So, it is both a win for "more documentation" and a win for "more test coverage". From 3fa94b1c6fbcee9012d48f747894cc6e14f993e0 Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:31:55 +0200 Subject: [PATCH 07/86] merge error? --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 063974615f90..9ce27a83c8bf 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -96,11 +96,9 @@ which tests your crate in a different way than unit tests. So, it is both a win You can also consider having an `# Error` section optionally. Of course, this only applies if there is a `Result` being returned, and if the `Error` variants are overly complicated. -Strive to include correct links to other items in your written docs as much as possible. In other words, avoid -\`some_func\` and instead use \[\`some_fund\`\]. Read more about how to correctly use links in your rust-docs +Strive to include correct links to other items in your written docs as much as possible. Read more about how to correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and -[here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). Strive to -include correct links to other items in your written docs as much as possible. In other words, avoid `` `some_func` `` +[here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). In other words, avoid `` `some_func` `` and instead use ``[`some_func`]``. > While you are linking, you might become conscious of the fact that you are in need of linking to (too many) foreign From 32f9a0dfbcc109a3d62df990f181c02730664ce9 Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:41:59 +0200 Subject: [PATCH 08/86] typo --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 9ce27a83c8bf..6b85be4896d7 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -143,7 +143,7 @@ The following are a set of notes that may not necessarily hold in all circumstan You should make sure that your code is properly-named and well-organized so that your code functions as a form of documentation. However, within the complexity of our projects in Polkadot/Substrate that is not enough. Particularly, -things like examples, errors and panics cannot be documented only through properly- named and well-organized code. +things like examples, errors and panics cannot be documented only through properly-named and well-organized code. > Our north star is self-documenting code that also happens to be well-documented and littered with examples. From 394661530eef8569722ac71a12ee7dbfbd952165 Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 22 Jul 2024 18:43:54 +0200 Subject: [PATCH 09/86] consistency --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 6b85be4896d7..79308d22a2a6 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -270,7 +270,7 @@ For the top-level pallet docs, consider the following template: //! up> ``` -This template's details (heading 3s and beyond) are left flexible, and at the discretion of the developer to make the +This template's details (Heading 3s and beyond) are left flexible, and at the discretion of the developer to make the best final choice about. For example, you might want to include `### Terminology` or not. Moreover, you might find it more useful to include it in `## Overview`. From b47be41981ae91d0860b9ddb93f767e541c565e0 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 12:32:47 +0200 Subject: [PATCH 10/86] typo --- docs/sdk/src/reference_docs/development_environment_advice.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/development_environment_advice.rs b/docs/sdk/src/reference_docs/development_environment_advice.rs index 9ba95dfa0329..996b0d55f8a6 100644 --- a/docs/sdk/src/reference_docs/development_environment_advice.rs +++ b/docs/sdk/src/reference_docs/development_environment_advice.rs @@ -145,7 +145,7 @@ //! } //! ``` //! -//! //! and the same in Lua for `neovim/nvim-lspconfig`: +//! and the same in Lua for `neovim/nvim-lspconfig`: //! //! ```lua //! ["rust-analyzer"] = { From c4ecce19e4c1350334eba72b1c585c7aa582d066 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 14:57:24 +0200 Subject: [PATCH 11/86] typo --- docs/sdk/src/polkadot_sdk/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index 124d391421b9..b321c545261a 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -116,7 +116,7 @@ //! [`polkadot`]: crate::polkadot_sdk::polkadot //! [`xcm`]: crate::polkadot_sdk::xcm -/// Lean about Cumulus, the framework that transforms [`substrate`]-based chains into +/// Learn about Cumulus, the framework that transforms [`substrate`]-based chains into /// [`polkadot`]-enabled parachains. pub mod cumulus; /// Learn about FRAME, the framework used to build Substrate runtimes. From e86bf9fc1302d15c54e32889f3e5b233ea55b63d Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 14:57:32 +0200 Subject: [PATCH 12/86] Link to readable manifesto pdf --- docs/sdk/src/polkadot_sdk/mod.rs | 2 +- docs/sdk/src/polkadot_sdk/polkadot.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index b321c545261a..fd12937a7852 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -12,7 +12,7 @@ //! //! [![RFCs](https://img.shields.io/badge/fellowship-RFCs-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/rfcs) //! [![Runtime](https://img.shields.io/badge/fellowship-runtimes-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/runtimes) -//! [![Manifesto](https://img.shields.io/badge/fellowship-manifesto-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/manifesto) +//! [![Manifesto](https://img.shields.io/badge/fellowship-manifesto-e6007a?logo=polkadot)](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf) //! //! ## Getting Started //! diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index e2dcca4dc7df..35ac9003a54c 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -8,7 +8,7 @@ //! - [Polkadot Parachains](https://parachains.info/) //! - [Polkadot (multi-chain) Explorer: Subscan](https://subscan.io/) //! - Polkadot Fellowship -//! - [Manifesto](https://github.com/polkadot-fellows/manifesto) +//! - [Manifesto](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf) //! - [Runtimes](https://github.com/polkadot-fellows/runtimes) //! - [RFCs](https://github.com/polkadot-fellows/rfcs) //! - [Dashboard](https://polkadot-fellows.github.io/dashboard/) From 04d9b69399bec06e92c61a0d9832ba78f44d6fd9 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 15:00:44 +0200 Subject: [PATCH 13/86] typo --- docs/sdk/src/polkadot_sdk/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index fd12937a7852..d7b836a1db0b 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -34,7 +34,7 @@ //! Repo](https://img.shields.io/badge/github-substrate-2324CC85)](https://github.com/paritytech/polkadot-sdk/blob/master/substrate) //! //! [`substrate`] is the base blockchain framework used to power the Polkadot SDK. It is a full -//! toolkit to create sovereign blockchains, including but not limited to those who connect to +//! toolkit to create sovereign blockchains, including but not limited to those which connect to //! Polkadot as parachains. //! //! #### FRAME From 6bc4f392bc64f8d604ee13edd127b8115ca959c2 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 15:06:24 +0200 Subject: [PATCH 14/86] explicity not needed here? --- docs/sdk/src/polkadot_sdk/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index d7b836a1db0b..04f0dc9c678e 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -82,7 +82,7 @@ //! //! A Substrate-based chain is a blockchain composed of a runtime and a node. As noted above, the //! runtime is the application logic of the blockchain, and the node is everything else. -//! See [`crate::reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The +//! See [`reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The //! former is built with [`frame`], and the latter is built with rest of Substrate. //! //! > You can think of a Substrate-based chain as a white-labeled blockchain. From 6e516734d9cb3985c958b7c24c4e3f769ad12ab9 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 15:18:16 +0200 Subject: [PATCH 15/86] typo --- docs/sdk/src/polkadot_sdk/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index 04f0dc9c678e..4de6be2bcae1 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -103,7 +103,7 @@ //! //! ## Trophy Section: Notable Downstream Projects //! -//! A list of projects and tools in the blockchain ecosystem that one way or another parts of the +//! A list of projects and tools in the blockchain ecosystem that one way or another use parts of the //! Polkadot SDK: //! //! * [Polygon's spin-off, Avail](https://github.com/availproject/avail) From 057105cd635dc22e352e16e1dd11e0a71d4d2f77 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 15:20:42 +0200 Subject: [PATCH 16/86] grammar? --- docs/sdk/src/polkadot_sdk/substrate.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index 69d74d86db1b..9a29ad59e786 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -11,7 +11,7 @@ //! 1. Society and technology evolves. //! 2. Humans are fallible. //! -//! This, makes the task of designing a correct, safe and long-lasting blockchain system hard. +//! This makes the task of designing a correct, safe and long-lasting blockchain system hard. //! //! Nonetheless, in strive towards achieve this goal, Substrate embraces the following: //! From 713d59bb8031869816768707cc98093fd02b07a5 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 15:24:01 +0200 Subject: [PATCH 17/86] typo --- docs/sdk/src/polkadot_sdk/substrate.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index 9a29ad59e786..27aebd7ffdc8 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -13,7 +13,7 @@ //! //! This makes the task of designing a correct, safe and long-lasting blockchain system hard. //! -//! Nonetheless, in strive towards achieve this goal, Substrate embraces the following: +//! Nonetheless, in strive towards achieving this goal, Substrate embraces the following: //! //! 1. Use of **Rust** as a modern and safe programming language, which limits human error through //! various means, most notably memory and type safety. From afca91dcbd82f37f2e99f4bb2e6ff97639d1a66a Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 16:05:17 +0200 Subject: [PATCH 18/86] typo --- docs/sdk/src/polkadot_sdk/substrate.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index 27aebd7ffdc8..c8f8228688d6 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -63,7 +63,7 @@ //! categories: //! //! * `sc-*` (short for *Substrate-client*) crates, located under `./client` folder. These are all -//! the crates that lead to the node software. Notable examples [`sc_network`], various consensus +//! the crates that lead to the node software. Notable examples are [`sc_network`], various consensus //! crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are expected to //! reside in the node side. //! * `sp-*` (short for *substrate-primitives*) crates, located under `./primitives` folder. These From d30896e49d2ca8222cf69951a16c3fa59df3e026 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 16:05:29 +0200 Subject: [PATCH 19/86] correct path --- docs/sdk/src/polkadot_sdk/substrate.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index c8f8228688d6..8867a8589b42 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -86,7 +86,7 @@ //! //! Substrate-based runtimes use [`substrate_wasm_builder`] in their `build.rs` to automatically //! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the -//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}.wasm`. +//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}/{runtime_name}.wasm`. //! //! ### Binaries //! From c2a2fd138b134cf8e9cc4b73d39ad262898711ba Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 16:26:49 +0200 Subject: [PATCH 20/86] Consistent case --- docs/sdk/src/polkadot_sdk/polkadot.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 35ac9003a54c..47f81ac97855 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -80,7 +80,7 @@ //! Within the scope of Polkadot 1.x, two main scheduling ways have been considered: //! //! * Long term Parachains, obtained through locking a sum of DOT in an auction system. -//! * on-demand Parachains, purchased through paying DOT to the relay-chain whenever needed. +//! * On-demand Parachains, purchased through paying DOT to the relay-chain whenever needed. //! //! ### The Future //! From d443f5dd12b263aab5a258b4e220d7135a71d37e Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 16:27:48 +0200 Subject: [PATCH 21/86] Broken link --- docs/sdk/src/polkadot_sdk/polkadot.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 47f81ac97855..1ce9ee24b1b0 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -12,7 +12,7 @@ //! - [Runtimes](https://github.com/polkadot-fellows/runtimes) //! - [RFCs](https://github.com/polkadot-fellows/rfcs) //! - [Dashboard](https://polkadot-fellows.github.io/dashboard/) -//! - [Polkadot Specs](spec.polkadot.network) +//! - [Polkadot Specs](http://spec.polkadot.network) //! - [The Polkadot Parachain Host Implementers' Guide](https://paritytech.github.io/polkadot-sdk/book/) //! - [Whitepaper](https://www.polkadot.network/whitepaper/) //! - [JAM Graypaper](https://graypaper.com) From 211a77421cb155091488dd78b4da3c0ff2974978 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 16:33:51 +0200 Subject: [PATCH 22/86] smoldot: link to docs because crates does not have a readme --- docs/sdk/src/polkadot_sdk/polkadot.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index 1ce9ee24b1b0..a1abc43f3189 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -19,7 +19,7 @@ //! //! ## Alternative Node Implementations 🌈 //! -//! - [Smoldot](https://crates.io/crates/smoldot-light). Polkadot light node/client. +//! - [Smoldot](https://docs.rs/crate/smoldot-light/latest). Polkadot light node/client. //! - [KAGOME](https://github.com/qdrvm/kagome). C++ implementation of the Polkadot host. //! - [Gossamer](https://github.com/ChainSafe/gossamer). Golang implementation of the Polkadot host. //! From a1e8e5708ad66b6bdb0a25989143aa2b0713cebd Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 16:38:02 +0200 Subject: [PATCH 23/86] single star --- docs/sdk/src/polkadot_sdk/polkadot.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/polkadot.rs b/docs/sdk/src/polkadot_sdk/polkadot.rs index a1abc43f3189..69532f323b9d 100644 --- a/docs/sdk/src/polkadot_sdk/polkadot.rs +++ b/docs/sdk/src/polkadot_sdk/polkadot.rs @@ -45,7 +45,7 @@ //! > their execution and governance sovereignty. These chains are called "Parachains". //! //! * Shared Security: The idea of shared economic security sits at the core of Polkadot. Polkadot -//! enables different parachains* to pool their economic security from Polkadot (i.e. "*Relay +//! enables different parachains to pool their economic security from Polkadot (i.e. "*Relay //! Chain*"). //! * (heterogenous) Sharded Execution: Yet, each parachain is free to have its own execution logic //! (runtime), which also encompasses governance and sovereignty. Moreover, Polkadot ensures the From 400ac58c33c6f6c7a6f1552ac3c55aeef3701098 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 17:56:39 +0200 Subject: [PATCH 24/86] typo --- docs/sdk/src/polkadot_sdk/frame_runtime.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/frame_runtime.rs b/docs/sdk/src/polkadot_sdk/frame_runtime.rs index 39255c8f51ad..4f89cfad9217 100644 --- a/docs/sdk/src/polkadot_sdk/frame_runtime.rs +++ b/docs/sdk/src/polkadot_sdk/frame_runtime.rs @@ -54,7 +54,7 @@ //! //! ### Example //! -//! The following examples showcases a minimal pallet. +//! The following example showcases a minimal pallet. #![doc = docify::embed!("src/polkadot_sdk/frame_runtime.rs", pallet)] //! //! From 69cb1d9bb3fbbf120cfa8a2af998d7e9a1a35e41 Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 18:03:43 +0200 Subject: [PATCH 25/86] typo --- docs/sdk/src/polkadot_sdk/frame_runtime.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/frame_runtime.rs b/docs/sdk/src/polkadot_sdk/frame_runtime.rs index 4f89cfad9217..a507960a4e5c 100644 --- a/docs/sdk/src/polkadot_sdk/frame_runtime.rs +++ b/docs/sdk/src/polkadot_sdk/frame_runtime.rs @@ -119,7 +119,7 @@ pub mod pallet { #[pallet::pallet] pub struct Pallet(PhantomData); - /// The events tha this pallet can emit. + /// The events that this pallet can emit. #[pallet::event] pub enum Event {} From 8ae9b8f3084c4d9e7666d635e431524943d3dadf Mon Sep 17 00:00:00 2001 From: rzadp Date: Tue, 23 Jul 2024 18:03:47 +0200 Subject: [PATCH 26/86] typo? --- docs/sdk/src/polkadot_sdk/frame_runtime.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/frame_runtime.rs b/docs/sdk/src/polkadot_sdk/frame_runtime.rs index a507960a4e5c..47114412aaa9 100644 --- a/docs/sdk/src/polkadot_sdk/frame_runtime.rs +++ b/docs/sdk/src/polkadot_sdk/frame_runtime.rs @@ -123,7 +123,7 @@ pub mod pallet { #[pallet::event] pub enum Event {} - /// A storage item that this pallet contains. This will be part of the state root trie/root + /// A storage item that this pallet contains. This will be part of the state root trie /// of the blockchain. #[pallet::storage] pub type Value = StorageValue; From 9d57bd77d1bebffbf88493724527d3b60ecb7a73 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 13:04:40 +0200 Subject: [PATCH 27/86] typo --- docs/sdk/src/polkadot_sdk/frame_runtime.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/frame_runtime.rs b/docs/sdk/src/polkadot_sdk/frame_runtime.rs index 47114412aaa9..8acf19f76413 100644 --- a/docs/sdk/src/polkadot_sdk/frame_runtime.rs +++ b/docs/sdk/src/polkadot_sdk/frame_runtime.rs @@ -85,7 +85,7 @@ //! [`crate::reference_docs::wasm_meta_protocol`]). Notable examples are: //! //! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template). -//! * writing a runtime in AssemblyScript,as explored in [this project](https://github.com/LimeChain/subsembly). +//! * writing a runtime in AssemblyScript, as explored in [this project](https://github.com/LimeChain/subsembly). /// A FRAME based pallet. This `mod` is the entry point for everything else. All /// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an From 307defa4028d1eb7d52fa90d9a2c165fedd46a87 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 16:57:24 +0200 Subject: [PATCH 28/86] Use links in xcm --- Cargo.lock | 4 ++++ docs/sdk/Cargo.toml | 4 ++++ docs/sdk/src/polkadot_sdk/xcm.rs | 11 +++++------ 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ead688ec9f56..545d20efb16f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -14572,6 +14572,7 @@ dependencies = [ "pallet-transaction-payment", "pallet-uniques", "pallet-utility", + "pallet-xcm", "parachain-template-runtime", "parity-scale-codec", "polkadot-sdk", @@ -14609,9 +14610,12 @@ dependencies = [ "staging-node-cli", "staging-parachain-info", "staging-xcm", + "staging-xcm-builder", + "staging-xcm-executor", "subkey", "substrate-wasm-builder", "xcm-docs", + "xcm-simulator", ] [[package]] diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index d3e48de5d181..e51fca1e9208 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -107,7 +107,11 @@ sp-version = { workspace = true, default-features = true } # XCM xcm = { workspace = true, default-features = true } +xcm-builder = { workspace = true } xcm-docs = { workspace = true } +xcm-executor = { workspace = true } +xcm-simulator = { workspace = true } +pallet-xcm = { workspace = true } # runtime guides chain-spec-guide-runtime = { workspace = true } diff --git a/docs/sdk/src/polkadot_sdk/xcm.rs b/docs/sdk/src/polkadot_sdk/xcm.rs index 58f540686424..57e18ff7b44b 100644 --- a/docs/sdk/src/polkadot_sdk/xcm.rs +++ b/docs/sdk/src/polkadot_sdk/xcm.rs @@ -34,12 +34,11 @@ //! but will be moved to its own repo in the future. //! //! Its main components are: -//! - `src`: the definition of the basic types and instructions -//! - [`xcm-executor`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm_executor/struct.XcmExecutor.html): -//! an implementation of the virtual machine to execute instructions -//! - `pallet-xcm`: A FRAME pallet for interacting with the executor -//! - `xcm-builder`: a collection of types to configure the executor -//! - `xcm-simulator`: a playground for trying out different XCM programs and executor +//! - [`xcm`](::xcm): the definition of the basic types and instructions +//! - [`xcm_executor`]: an implementation of the virtual machine to execute instructions +//! - [`pallet_xcm`]: A FRAME pallet for interacting with the executor +//! - [`xcm_builder`]: a collection of types to configure the executor +//! - [`xcm_simulator`]: a playground for trying out different XCM programs and executor //! configurations //! //! ## Example From a531494757095341794a12b59381847d900066a1 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 16:59:17 +0200 Subject: [PATCH 29/86] non-person --- docs/sdk/src/polkadot_sdk/xcm.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/xcm.rs b/docs/sdk/src/polkadot_sdk/xcm.rs index 57e18ff7b44b..85d013ef88ce 100644 --- a/docs/sdk/src/polkadot_sdk/xcm.rs +++ b/docs/sdk/src/polkadot_sdk/xcm.rs @@ -5,7 +5,7 @@ //! //! ## Overview //! -//! XCM is a standard, whose specification lives in the [xcm format repo](https://github.com/paritytech/xcm-format). +//! XCM is a standard, specification of which lives in the [xcm format repo](https://github.com/paritytech/xcm-format). //! It's agnostic both in programming language and blockchain platform, which means it could be used //! in Rust in Polkadot, or in Go or C++ in any other platform like Cosmos or Ethereum. //! From 838d5046364c0a8fccd9e467359785b4e1827d34 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 17:08:43 +0200 Subject: [PATCH 30/86] typo --- docs/sdk/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/lib.rs b/docs/sdk/src/lib.rs index e211476d2514..bc80460bc187 100644 --- a/docs/sdk/src/lib.rs +++ b/docs/sdk/src/lib.rs @@ -13,7 +13,7 @@ //! We suggest the following reading sequence: //! //! - Start by learning about the the [`polkadot_sdk`], its structure and context. -//! - Then, head over the [`guides`]. This modules contains in-depth guides about the most important +//! - Then, head over to the [`guides`]. This modules contains in-depth guides about the most important //! user-journeys of the Polkadot SDK. //! - Whilst reading the guides, you might find back-links to [`reference_docs`]. //! - Finally, is the parent website of this crate that contains the From b7eab4b181372882964114e25347965e54b20b6b Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 17:15:22 +0200 Subject: [PATCH 31/86] Link could be useful here when navigating straight to guides --- docs/sdk/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/lib.rs b/docs/sdk/src/lib.rs index bc80460bc187..1bd318cb5753 100644 --- a/docs/sdk/src/lib.rs +++ b/docs/sdk/src/lib.rs @@ -36,7 +36,7 @@ pub mod meta_contributing; /// In-depth guides about the most common components of the Polkadot SDK. They are slightly more -/// high level and broad than reference docs. +/// high level and broad than [`reference_docs`]. pub mod guides; /// An introduction to the Polkadot SDK. Read this module to learn about the structure of the SDK, /// the tools that are provided as a part of it, and to gain a high level understanding of each. From 46afa0ec7f52c60b7730824f2561d231efcf3eb5 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 17:20:01 +0200 Subject: [PATCH 32/86] Consistent phrase with the other guide. And if it is successful, that remains to be seen (for each user) --- docs/sdk/src/guides/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 9384f4c82ab3..833a86a82b5b 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -15,7 +15,7 @@ /// Write your first simple pallet, learning the most most basic features of FRAME along the way. pub mod your_first_pallet; -/// Writing your first real [runtime](`crate::reference_docs::wasm_meta_protocol`), and successfully +/// Write your first real [runtime](`crate::reference_docs::wasm_meta_protocol`), /// compiling it to [WASM](crate::polkadot_sdk::substrate#wasm-build). pub mod your_first_runtime; From 26e0da9622ff017f8afc2ff1832f5e2d757bb952 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 17:22:07 +0200 Subject: [PATCH 33/86] meaning --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index da4624f5ac2b..f4717bc52b33 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -1,6 +1,6 @@ //! # Currency Pallet //! -//! By the end of this guide, you will write a small FRAME pallet (see +//! By the end of this guide, you will have written a small FRAME pallet (see //! [`crate::polkadot_sdk::frame_runtime`]) that is capable of handling a simple crypto-currency. //! This pallet will: //! From f1968110239c2253077db5595c3caaf546396e52 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 17:27:39 +0200 Subject: [PATCH 34/86] typo --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index f4717bc52b33..68254e9f977c 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -18,7 +18,7 @@ //! //! To get started, use one of the templates mentioned in [`crate::polkadot_sdk::templates`]. We //! recommend using the `polkadot-sdk-minimal-template`. You might need to change small parts of -//! this guide, namely the crate/package names, based on which tutorial you use. +//! this guide, namely the crate/package names, based on which template you use. //! //! > Be aware that you can read the entire source code backing this tutorial by clicking on the //! > [`source`](./mod.rs.html) button at the top right of the page. From 32c895ac150592009f138c98eabdf9642abe6e79 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 17:38:12 +0200 Subject: [PATCH 35/86] typo --- docs/sdk/src/reference_docs/trait_based_programming.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/trait_based_programming.rs b/docs/sdk/src/reference_docs/trait_based_programming.rs index ace313880707..90b38f63a580 100644 --- a/docs/sdk/src/reference_docs/trait_based_programming.rs +++ b/docs/sdk/src/reference_docs/trait_based_programming.rs @@ -196,7 +196,7 @@ mod with_system { mod fully_qualified { use super::with_system::*; - // Simple of using fully qualified syntax. + // Example of using fully qualified syntax. type AccountIdOf = ::AccountId; } From 41c72f8955bf4f76d79f1bcc128e8ea981e5b953 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 19:21:30 +0200 Subject: [PATCH 36/86] grammar --- substrate/frame/support/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 06696488e298..3f2c1a4280d2 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1048,7 +1048,7 @@ pub mod pallet_prelude { /// If the attribute `set_storage_max_encoded_len` is set then the macro calls /// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for each storage in the /// implementation of [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the -/// pallet. Otherwise it implements +/// pallet. Otherwise, it implements /// [`StorageInfoTrait`](frame_support::traits::StorageInfoTrait) for the pallet using the /// [`PartialStorageInfoTrait`](frame_support::traits::PartialStorageInfoTrait) /// implementation of storages. From 835a7d2d42d85090945cb80e169af8519c59b24c Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 19:33:48 +0200 Subject: [PATCH 37/86] typo --- substrate/frame/support/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 3f2c1a4280d2..b9a5b773746d 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -935,7 +935,7 @@ pub mod pallet_prelude { /// /// # 1 - Pallet module declaration /// -/// The module to declare a pallet is organized as follow: +/// The module to declare a pallet is organized as follows: /// ``` /// #[frame_support::pallet] // <- the macro /// mod pallet { From 3a86ce50fe096d642490aabb49010b9b5502fc29 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 19:42:08 +0200 Subject: [PATCH 38/86] Fix a broken link - although it's not a very resourceful one --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 68254e9f977c..a4f6f6b277a0 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -45,7 +45,7 @@ //! Consider the following as a "shell pallet". We continue building the rest of this pallet based //! on this template. //! -//! [`pallet::config`] and [`pallet::pallet`] are both mandatory parts of any pallet. Refer to the +//! [`pallet::config`] and [`pallet::pallet`](frame_support::pallet) are both mandatory parts of any pallet. Refer to the //! documentation of each to get an overview of what they do. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", shell_pallet)] //! From c80bfdf59c51e25409e0d050286859035d07a958 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 20:27:48 +0200 Subject: [PATCH 39/86] feels better --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index a4f6f6b277a0..4c97ac1f34a7 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -73,7 +73,7 @@ //! as normal `fn`s attached to `struct Pallet`. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", impl_pallet)] //! -//! The logic of the functions is self-explanatory. Instead, we will focus on the FRAME-related +//! The logic of these functions is self-explanatory. Instead, we will focus on the FRAME-related //! details: //! //! - Where do `T::AccountId` and `T::RuntimeOrigin` come from? These are both defined in From 544c9a224afca65f10cfd8532d1ebee0378b26a4 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 20:32:57 +0200 Subject: [PATCH 40/86] invalid var --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 4c97ac1f34a7..1d11d6e05f9d 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -83,7 +83,7 @@ //! document ([`crate::reference_docs::frame_origin`]). For now, you should only know the //! signature of the function: it takes a generic `T::RuntimeOrigin` and returns a //! `Result`. So by the end of this function call, we know that this dispatchable -//! was signed by `who`. +//! was signed by `sender`. #![doc = docify::embed!("../../substrate/frame/system/src/lib.rs", ensure_signed)] //! //! - Where does `mutate`, `get` and `insert` and other storage APIs come from? All of them are From 6d52a6c102c08ed969b503a82dc68df23f5bcb25 Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 20:37:22 +0200 Subject: [PATCH 41/86] somehow the link works differently --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 1d11d6e05f9d..5b2f5008484e 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -96,7 +96,7 @@ //! Which is more or less a normal Rust `Result`, with a custom [`frame::prelude::DispatchError`] as //! the `Err` variant. We won't cover this error in detail here, but importantly you should know //! that there is an `impl From<&'static string> for DispatchError` provided (see -//! [here](`frame::prelude::DispatchError#impl-From<%26'static+str>-for-DispatchError`)). Therefore, +//! [here](`frame::prelude::DispatchError#impl-From<%26str>-for-DispatchError`)). Therefore, //! we can use basic string literals as our error type and `.into()` them into `DispatchError`. //! //! - Why are all `get` and `mutate` functions returning an `Option`? This is the default behavior From eae2d696f1704af6d71ff3a85453b5c7e9b5651c Mon Sep 17 00:00:00 2001 From: rzadp Date: Wed, 24 Jul 2024 20:39:14 +0200 Subject: [PATCH 42/86] typo --- docs/sdk/src/guides/your_first_pallet/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 5b2f5008484e..3e52317d4b79 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -117,7 +117,7 @@ //! ergonomic. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", transfer_better_checked)] //! -//! This is more or less all the logic that there is this basic currency pallet! +//! This is more or less all the logic that there is in this basic currency pallet! //! //! ### Your First (Test) Runtime //! From 0525f54a33dc2bbbd7e54c9fef97450a13474aa6 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 12:15:20 +0200 Subject: [PATCH 43/86] Looks like the setting name has changed --- docs/sdk/src/reference_docs/development_environment_advice.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/development_environment_advice.rs b/docs/sdk/src/reference_docs/development_environment_advice.rs index 996b0d55f8a6..e9ed37c435ea 100644 --- a/docs/sdk/src/reference_docs/development_environment_advice.rs +++ b/docs/sdk/src/reference_docs/development_environment_advice.rs @@ -16,7 +16,7 @@ //! { //! // Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust //! // Analyzer and cargo on the command line at the same time. -//! "rust-analyzer.rust.analyzerTargetDir": "target/vscode-rust-analyzer", +//! "rust-analyzer.cargo.targetDir": "target/vscode-rust-analyzer", //! // Improve stability //! "rust-analyzer.server.extraEnv": { //! "CHALK_OVERFLOW_DEPTH": "100000000", From 7e6ec687335dc8362985a3753a684e780928ad17 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 12:15:33 +0200 Subject: [PATCH 44/86] Add a tradeoff disclaimer --- docs/sdk/src/reference_docs/development_environment_advice.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/development_environment_advice.rs b/docs/sdk/src/reference_docs/development_environment_advice.rs index e9ed37c435ea..a5f38bb280de 100644 --- a/docs/sdk/src/reference_docs/development_environment_advice.rs +++ b/docs/sdk/src/reference_docs/development_environment_advice.rs @@ -15,7 +15,8 @@ //! ```json //! { //! // Use a separate target dir for Rust Analyzer. Helpful if you want to use Rust -//! // Analyzer and cargo on the command line at the same time. +//! // Analyzer and cargo on the command line at the same time, +//! // at the expense of duplicating build artifacts. //! "rust-analyzer.cargo.targetDir": "target/vscode-rust-analyzer", //! // Improve stability //! "rust-analyzer.server.extraEnv": { From 5206e84c0d4cb77dda0b4eeaa8f6198ba4d418b0 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 13:10:19 +0200 Subject: [PATCH 45/86] format --- docs/sdk/src/reference_docs/defensive_programming.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/reference_docs/defensive_programming.rs b/docs/sdk/src/reference_docs/defensive_programming.rs index 9828e1b50918..678323d6432d 100644 --- a/docs/sdk/src/reference_docs/defensive_programming.rs +++ b/docs/sdk/src/reference_docs/defensive_programming.rs @@ -16,7 +16,7 @@ //! [Defensive programming](https://en.wikipedia.org/wiki/Defensive_programming) is a design paradigm that enables a program to continue //! running despite unexpected behavior, input, or events that may arise in runtime. //! Usually, unforeseen circumstances may cause the program to stop or, in the Rust context, -//! panic!. Defensive practices allow for these circumstances to be accounted for ahead of time +//! `panic!`. Defensive practices allow for these circumstances to be accounted for ahead of time //! and for them to be handled gracefully, which is in line with the intended fault-tolerant and //! deterministic nature of blockchains. //! @@ -71,7 +71,7 @@ //! ### Defensive Traits //! //! The [`Defensive`](frame::traits::Defensive) trait provides a number of functions, all of which -//! provide an alternative to 'vanilla' Rust functions, e.g.,: +//! provide an alternative to 'vanilla' Rust functions, e.g.: //! //! - [`defensive_unwrap_or()`](frame::traits::Defensive::defensive_unwrap_or) instead of //! `unwrap_or()` From 3e0f687b291d5a3db6f7360416b299074169a125 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 13:17:02 +0200 Subject: [PATCH 46/86] gramma? --- docs/sdk/src/reference_docs/defensive_programming.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/defensive_programming.rs b/docs/sdk/src/reference_docs/defensive_programming.rs index 678323d6432d..82d624b01d97 100644 --- a/docs/sdk/src/reference_docs/defensive_programming.rs +++ b/docs/sdk/src/reference_docs/defensive_programming.rs @@ -127,7 +127,7 @@ //! - [Fixed point types](sp_arithmetic::fixed_point) and their associated usage can be found here. //! - [PerThing](sp_arithmetic::per_things) and its associated types can be found here. //! -//! Using floating point number types (i.e., f32. f64) in the runtime should be avoided, as a single non-deterministic result could cause chaos for blockchain consensus along with the issues above. For more on the specifics of the peculiarities of floating point calculations, [watch this video by the Computerphile](https://www.youtube.com/watch?v=PZRI1IfStY0). +//! Using floating point number types (i.e. f32, f64) in the runtime should be avoided, as a single non-deterministic result could cause chaos for blockchain consensus along with the issues above. For more on the specifics of the peculiarities of floating point calculations, [watch this video by the Computerphile](https://www.youtube.com/watch?v=PZRI1IfStY0). //! //! The following methods demonstrate different ways to handle numbers natively in Rust safely, //! without fear of panic or unexpected behavior from wrapping. From 7a446d0a1b525d9fab24ce77f4a1c09cc247502a Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 15:00:49 +0200 Subject: [PATCH 47/86] display --- docs/sdk/src/reference_docs/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/reference_docs/mod.rs b/docs/sdk/src/reference_docs/mod.rs index c69c79365427..98dbfcccac21 100644 --- a/docs/sdk/src/reference_docs/mod.rs +++ b/docs/sdk/src/reference_docs/mod.rs @@ -52,8 +52,8 @@ pub mod frame_storage_derives; /// Learn about how to write safe and defensive code in your FRAME runtime. pub mod defensive_programming; -/// Learn about composite enums and other runtime level types, such as "RuntimeEvent" and -/// "RuntimeCall". +/// Learn about composite enums and other runtime level types, such as `RuntimeEvent` and +/// `RuntimeCall`. pub mod frame_runtime_types; /// Learn about how to make a pallet/runtime that is fee-less and instead uses another mechanism to From a7cf311a3e4db88464565590bc96166e5233d906 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 15:20:54 +0200 Subject: [PATCH 48/86] this format didnt work in a div --- docs/sdk/src/guides/async_backing_guide.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index f2f4dcabfd29..ba3a59c5ce52 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -27,7 +27,7 @@ //! "scheduling_lookahead": 2 //! ``` //! -//!
`scheduling_lookahead` must be set to 2, otherwise parachain block times +//!
scheduling_lookahead must be set to 2, otherwise parachain block times //! will degrade to worse than with sync backing!
//! //! ## Phase 1 - Update Parachain Runtime From 41cfdbda7d132767758f1b3f712b7dd31b93b63c Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 19:50:36 +0200 Subject: [PATCH 49/86] Make link clickable inside the div --- docs/sdk/src/guides/enable_elastic_scaling_mvp.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs index bc4f36c271fe..91d28b40b275 100644 --- a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs +++ b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs @@ -1,7 +1,7 @@ //! # Enable elastic scaling MVP for a parachain //! //!
This guide assumes full familiarity with Asynchronous Backing and its -//! terminology, as defined in https://wiki.polkadot.network/docs/maintain-guides-async-backing. +//! terminology, as defined in the Polkadot Wiki. //! Furthermore, the parachain should have already been upgraded according to the guide.
//! //! ## Quick introduction to elastic scaling From 5da0e69e299c7f4c96bcc92a42d990b1b6ed343f Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 19:56:46 +0200 Subject: [PATCH 50/86] formatting inside a div --- docs/sdk/src/guides/enable_elastic_scaling_mvp.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs index 91d28b40b275..7768b3146e85 100644 --- a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs +++ b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs @@ -70,8 +70,8 @@ //! - Ensure enough coretime is assigned to the parachain. For maximum throughput the upper bound is //! 3 cores. //! -//!
Phase 1 is not needed if using the `polkadot-parachain` binary built -//! from the latest polkadot-sdk release! Simply pass the `--experimental-use-slot-based` parameter +//!
Phase 1 is not needed if using the polkadot-parachain binary built +//! from the latest polkadot-sdk release! Simply pass the --experimental-use-slot-based parameter //! to the command line and jump to Phase 2.
//! //! The following steps assume using the cumulus parachain template. From e1925b9231161e864181ff572db046551f141c0e Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 20:03:13 +0200 Subject: [PATCH 51/86] those docs were slurped by the next uncommented mod! --- docs/sdk/src/guides/mod.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 833a86a82b5b..310a6c44de9b 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -19,17 +19,17 @@ pub mod your_first_pallet; /// compiling it to [WASM](crate::polkadot_sdk::substrate#wasm-build). pub mod your_first_runtime; -/// Running the given runtime with a node. No specific consensus mechanism is used at this stage. +// /// Running the given runtime with a node. No specific consensus mechanism is used at this stage. // TODO // pub mod your_first_node; -/// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain and connect -/// it to a relay-chain. +// /// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain and connect +// /// it to a relay-chain. // TODO // pub mod cumulus_enabled_parachain; -/// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between itself -/// and the relay chain to which it is connected. +// /// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between itself +// /// and the relay chain to which it is connected. // TODO // pub mod xcm_enabled_parachain; From 1847edba169f45d3f5b519140461b7046f11f547 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 20:05:35 +0200 Subject: [PATCH 52/86] separation between the comment on pub mod - consistent with others --- docs/sdk/src/guides/enable_pov_reclaim.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sdk/src/guides/enable_pov_reclaim.rs b/docs/sdk/src/guides/enable_pov_reclaim.rs index 3c0c5fba2158..13b27d18956b 100644 --- a/docs/sdk/src/guides/enable_pov_reclaim.rs +++ b/docs/sdk/src/guides/enable_pov_reclaim.rs @@ -1,3 +1,5 @@ +//! # Enable storage weight reclaiming +//! //! This guide will teach you how to enable storage weight reclaiming for a parachain. The //! explanations in this guide assume a project structure similar to the one detailed in //! the [substrate documentation](crate::polkadot_sdk::substrate#anatomy-of-a-binary-crate). Full From 04a64a74cdcd8cc31f236f34f7241f6c9b6055c5 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 20:10:33 +0200 Subject: [PATCH 53/86] typos --- docs/sdk/src/guides/enable_metadata_hash.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/guides/enable_metadata_hash.rs b/docs/sdk/src/guides/enable_metadata_hash.rs index b9cbae853353..f64408e3a2f6 100644 --- a/docs/sdk/src/guides/enable_metadata_hash.rs +++ b/docs/sdk/src/guides/enable_metadata_hash.rs @@ -16,8 +16,8 @@ //! the metadata for one or more networks. The next problem is that the offline wallet/user can not //! trust the metadata to be correct. It is very important for the metadata to be correct or //! otherwise an attacker could change them in a way that the offline wallet decodes a transaction -//! in a different way than what it will be decoded to on chain. So, the user may signs an incorrect -//! transaction leading to unexpecting behavior. +//! in a different way than what it will be decoded to on chain. So, the user may sign an incorrect +//! transaction leading to unexpected behavior. //! //! The metadata hash verification circumvents the issues of the huge metadata and the need to trust //! some metadata blob to be correct. To generate a hash for the metadata, the metadata is chunked, From 5363451b226a56c96cffb01c7044b7eb584ac2c6 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 20:10:37 +0200 Subject: [PATCH 54/86] I guess? --- docs/sdk/src/guides/enable_metadata_hash.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/guides/enable_metadata_hash.rs b/docs/sdk/src/guides/enable_metadata_hash.rs index f64408e3a2f6..930afd4d8ff7 100644 --- a/docs/sdk/src/guides/enable_metadata_hash.rs +++ b/docs/sdk/src/guides/enable_metadata_hash.rs @@ -24,7 +24,7 @@ //! these chunks are put into a merkle tree and then the root of this merkle tree is the "metadata //! hash". For a more technical explanation on how it works, see //! [RFC78](https://polkadot-fellows.github.io/RFCs/approved/0078-merkleized-metadata.html). At compile -//! time the metadata hash is generated and "backed" into the runtime. This makes it extremely cheap +//! time the metadata hash is generated and "baked" into the runtime. This makes it extremely cheap //! for the runtime to verify on chain that the metadata hash is correct. By having the runtime //! verify the hash on chain, the user also doesn't need to trust the offchain metadata. If the //! metadata hash doesn't match the on chain metadata hash the transaction will be rejected. The From 3aa4c47c0755c642005e8910ed06ecd2c77dcf25 Mon Sep 17 00:00:00 2001 From: rzadp Date: Thu, 25 Jul 2024 20:19:00 +0200 Subject: [PATCH 55/86] broken links --- docs/sdk/src/reference_docs/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/reference_docs/mod.rs b/docs/sdk/src/reference_docs/mod.rs index 98dbfcccac21..3eabab75b725 100644 --- a/docs/sdk/src/reference_docs/mod.rs +++ b/docs/sdk/src/reference_docs/mod.rs @@ -7,8 +7,8 @@ //! //! ## What is a "reference document"? //! -//! First, see [why we use rust-docs for everything](crate#why-rust-docs) and our documentation -//! [principles](crate#principles). We acknowledge that as much of the crucial information should be +//! First, see [why we use rust-docs for everything](crate::meta_contributing#why-rust-docs) and our documentation +//! [principles](crate::meta_contributing#principles). We acknowledge that as much of the crucial information should be //! embedded in the low level rust-docs. Then, high level scenarios should be covered in //! [`crate::guides`]. Finally, we acknowledge that there is a category of information that is: //! From 83d345ff049be1ac7cc9f8a7275cf851fe24a89e Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 11:37:15 +0200 Subject: [PATCH 56/86] format --- docs/sdk/src/reference_docs/metadata.rs | 4 ++-- docs/sdk/src/reference_docs/umbrella_crate.rs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sdk/src/reference_docs/metadata.rs b/docs/sdk/src/reference_docs/metadata.rs index 96f92ac0c412..485614088140 100644 --- a/docs/sdk/src/reference_docs/metadata.rs +++ b/docs/sdk/src/reference_docs/metadata.rs @@ -21,5 +21,5 @@ //! //! A few noteworthy tools that inspect the (FRAME-based) metadata of a chain: //! -//! -//! +//! - +//! - diff --git a/docs/sdk/src/reference_docs/umbrella_crate.rs b/docs/sdk/src/reference_docs/umbrella_crate.rs index 0b3445cfc4bc..7721b1b74d30 100644 --- a/docs/sdk/src/reference_docs/umbrella_crate.rs +++ b/docs/sdk/src/reference_docs/umbrella_crate.rs @@ -25,7 +25,7 @@ //! - `runtime`: As described above, enable all `no-std` crates. //! - `node`: As described above, enable all `std` crates. //! - There does *not* exist a dedicated docs feature. To generate docs, enable the `runtime` and -//! `node` feature. For docs.rs the manifest contains specific configuration to make it show up +//! `node` feature. For `docs.rs` the manifest contains specific configuration to make it show up //! all re-exports. //! //! There is a specific [`zepter`](https://github.com/ggwpez/zepter) check in place to ensure that From 65a49058dd07c6aca085143350b3b6fe57d8e64c Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 11:42:32 +0200 Subject: [PATCH 57/86] link to report issues --- docs/sdk/src/reference_docs/umbrella_crate.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/umbrella_crate.rs b/docs/sdk/src/reference_docs/umbrella_crate.rs index 7721b1b74d30..1074cde37693 100644 --- a/docs/sdk/src/reference_docs/umbrella_crate.rs +++ b/docs/sdk/src/reference_docs/umbrella_crate.rs @@ -77,7 +77,7 @@ //! ``` //! //! Apart from this, no issues are known. There could be some bugs with how macros locate their own -//! re-exports. Please compile issues that arise from using this crate. +//! re-exports. Please [report issues](https://github.com/paritytech/polkadot-sdk/issues) that arise from using this crate. //! //! ## Dependencies //! From 33e9352f45541c1d75cc5b052f0c5feb51288950 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:06:30 +0200 Subject: [PATCH 58/86] unnecessary double comment? can display it to the consumer --- docs/sdk/src/reference_docs/frame_system_accounts.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_system_accounts.rs b/docs/sdk/src/reference_docs/frame_system_accounts.rs index 523fe7043084..c93e1196ea7e 100644 --- a/docs/sdk/src/reference_docs/frame_system_accounts.rs +++ b/docs/sdk/src/reference_docs/frame_system_accounts.rs @@ -1,6 +1,6 @@ //! # FRAME Accounts //! -//! //! 🚧 Work In Progress 🚧 +//! 🚧 Work In Progress 🚧 //! //! How `frame_system` handles accountIds. Nonce. Consumers and Providers, reference counting. From e351a7189f66db28598356d56ddf215718d68a9b Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:21:11 +0200 Subject: [PATCH 59/86] that class has no css --- docs/sdk/src/reference_docs/frame_storage_derives.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_storage_derives.rs b/docs/sdk/src/reference_docs/frame_storage_derives.rs index 3d9edef398a0..1c2b14af1e46 100644 --- a/docs/sdk/src/reference_docs/frame_storage_derives.rs +++ b/docs/sdk/src/reference_docs/frame_storage_derives.rs @@ -1,6 +1,6 @@ -//!
-//! In all examples, a few lines of boilerplate have been hidden from each snippet for conciseness. -//!
+//! > **Note:** +//! > +//! > In all examples, a few lines of boilerplate have been hidden from each snippet for conciseness. //! //! Let's begin by starting to store a `NewType` in a storage item: //! From e746cf25f5c8b85b49d7a650fdb677d19cd9d940 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:21:20 +0200 Subject: [PATCH 60/86] title for consistency --- docs/sdk/src/reference_docs/frame_storage_derives.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sdk/src/reference_docs/frame_storage_derives.rs b/docs/sdk/src/reference_docs/frame_storage_derives.rs index 1c2b14af1e46..8e73c9d7c51b 100644 --- a/docs/sdk/src/reference_docs/frame_storage_derives.rs +++ b/docs/sdk/src/reference_docs/frame_storage_derives.rs @@ -1,3 +1,5 @@ +//! # Frame storage derives +//! //! > **Note:** //! > //! > In all examples, a few lines of boilerplate have been hidden from each snippet for conciseness. From a0184e58e0f4a6d3621c76e0fd4c72913f95b42d Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:22:59 +0200 Subject: [PATCH 61/86] stylistics, feels better --- docs/sdk/src/reference_docs/frame_storage_derives.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_storage_derives.rs b/docs/sdk/src/reference_docs/frame_storage_derives.rs index 8e73c9d7c51b..359d073b63c3 100644 --- a/docs/sdk/src/reference_docs/frame_storage_derives.rs +++ b/docs/sdk/src/reference_docs/frame_storage_derives.rs @@ -136,7 +136,7 @@ //! - [`frame::prelude::PartialOrdNoBound`] //! - [`frame::prelude::OrdNoBound`] //! -//! The above traits are almost certainly needed for your tests: To print your type, assert equality +//! The above traits are almost certainly needed for your tests - to print your type, assert equality //! or clone it. //! //! We can fix the following example by using [`frame::prelude::DefaultNoBound`]. From 5ec9b2a357237ba0cb1e4fcd3ecd1817697c1964 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:24:41 +0200 Subject: [PATCH 62/86] unncesessary in enumeration --- .../src/reference_docs/frame_runtime_upgrades_and_migrations.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs index f9a69b892a31..ffdbb83ade93 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs @@ -2,7 +2,7 @@ //! //! At their core, blockchain logic consists of //! -//! 1. on-chain state and +//! 1. on-chain state //! 2. a state transition function //! //! In Substrate-based blockchains, state transition functions are referred to as From 643673494b2b5a49c9de72d454ee2a07d5f6a076 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:27:39 +0200 Subject: [PATCH 63/86] Try to apply some consistency in lists --- docs/sdk/src/reference_docs/frame_logging.rs | 2 +- docs/sdk/src/reference_docs/frame_pallet_coupling.rs | 8 ++++---- .../frame_runtime_upgrades_and_migrations.rs | 4 ++-- docs/sdk/src/reference_docs/mod.rs | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_logging.rs b/docs/sdk/src/reference_docs/frame_logging.rs index 301fa7ef83f8..2526bbadde20 100644 --- a/docs/sdk/src/reference_docs/frame_logging.rs +++ b/docs/sdk/src/reference_docs/frame_logging.rs @@ -36,7 +36,7 @@ //! //! First, ensure you are familiar with the `log` crate. In short, each log statement has: //! -//! 1. `log-level`, signifying how important it is +//! 1. `log-level`, signifying how important it is. //! 2. `log-target`, signifying to which component it belongs. //! //! Add log statements to your pallet as such: diff --git a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs index be464bbbf835..285fc71d9dea 100644 --- a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs +++ b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs @@ -30,8 +30,8 @@ //! //! There are generally two ways to achieve this: //! -//! 1. Tight coupling pallets -//! 2. Loose coupling pallets +//! 1. Tight coupling pallets. +//! 2. Loose coupling pallets. //! //! To explain the difference between the two, consider two pallets, `A` and `B`. In both cases, `A` //! wants to use some functionality exposed by `B`. @@ -74,8 +74,8 @@ //! pallet makes its own `trait Config` be bounded by another pallet's `trait Config`, it is //! expressing two things: //! -//! 1. that it can only exist in a runtime if the other pallet is also present. -//! 2. that it can use the other pallet's functionality. +//! 1. That it can only exist in a runtime if the other pallet is also present. +//! 2. That it can use the other pallet's functionality. //! //! `pallet-foo`'s `Config` would then look like: #![doc = docify::embed!("./src/reference_docs/frame_pallet_coupling.rs", tight_config)] diff --git a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs index ffdbb83ade93..9ab7233937f5 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs @@ -2,8 +2,8 @@ //! //! At their core, blockchain logic consists of //! -//! 1. on-chain state -//! 2. a state transition function +//! 1. on-chain state, +//! 2. a state transition function. //! //! In Substrate-based blockchains, state transition functions are referred to as //! [runtimes](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/blockchain_state_machines/index.html). diff --git a/docs/sdk/src/reference_docs/mod.rs b/docs/sdk/src/reference_docs/mod.rs index 3eabab75b725..04a05837c5ef 100644 --- a/docs/sdk/src/reference_docs/mod.rs +++ b/docs/sdk/src/reference_docs/mod.rs @@ -12,9 +12,9 @@ //! embedded in the low level rust-docs. Then, high level scenarios should be covered in //! [`crate::guides`]. Finally, we acknowledge that there is a category of information that is: //! -//! 1. crucial to know. -//! 2. is too high level to be in the rust-doc of any one `type`, `trait` or `fn`. -//! 3. is too low level to be encompassed in a [`crate::guides`]. +//! 1. Crucial to know. +//! 2. Is too high level to be in the rust-doc of any one `type`, `trait` or `fn`. +//! 3. Is too low level to be encompassed in a [`crate::guides`]. //! //! We call this class of documents "reference documents". Our goal should be to minimize the number //! of "reference" docs, as they incur maintenance burden. From 1e2185fb138c5992ce4b73171884e81b5bcb29a5 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:30:50 +0200 Subject: [PATCH 64/86] explain term used for the first time --- docs/sdk/src/polkadot_sdk/substrate.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index 8867a8589b42..e9edf9d95bda 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -27,7 +27,7 @@ //! blob. //! //! In essence, the meta-protocol of all Substrate based chains is the "Runtime as WASM blob" -//! accord. This enables the Runtime to become inherently upgradeable, crucially without forks. The +//! accord. This enables the Runtime to become inherently upgradeable, crucially without [forks](https://en.wikipedia.org/wiki/Fork_(blockchain)). The //! upgrade is merely a matter of the WASM blob being changed in the state, which is, in principle, //! same as updating an account's balance. Learn more about this in detail in //! [`crate::reference_docs::wasm_meta_protocol`]. From 698e98a69ecdfdf83fb3f712f325ac0e1d067bbf Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:44:28 +0200 Subject: [PATCH 65/86] Try to apply some consistency in lists --- docs/sdk/src/polkadot_sdk/xcm.rs | 12 ++++++------ .../src/reference_docs/frame_benchmarking_weight.rs | 8 ++++---- .../frame_runtime_upgrades_and_migrations.rs | 12 ++++++------ 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/sdk/src/polkadot_sdk/xcm.rs b/docs/sdk/src/polkadot_sdk/xcm.rs index 85d013ef88ce..20841b0b55b9 100644 --- a/docs/sdk/src/polkadot_sdk/xcm.rs +++ b/docs/sdk/src/polkadot_sdk/xcm.rs @@ -34,12 +34,12 @@ //! but will be moved to its own repo in the future. //! //! Its main components are: -//! - [`xcm`](::xcm): the definition of the basic types and instructions -//! - [`xcm_executor`]: an implementation of the virtual machine to execute instructions -//! - [`pallet_xcm`]: A FRAME pallet for interacting with the executor -//! - [`xcm_builder`]: a collection of types to configure the executor -//! - [`xcm_simulator`]: a playground for trying out different XCM programs and executor -//! configurations +//! - [`xcm`](::xcm): The definition of the basic types and instructions. +//! - [`xcm_executor`]: An implementation of the virtual machine to execute instructions. +//! - [`pallet_xcm`]: A FRAME pallet for interacting with the executor. +//! - [`xcm_builder`]: A collection of types to configure the executor. +//! - [`xcm_simulator`]: A playground for trying out different XCM programs and executor +//! configurations. //! //! ## Example //! diff --git a/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs b/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs index db77547a4bf0..cf9e58791492 100644 --- a/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs +++ b/docs/sdk/src/reference_docs/frame_benchmarking_weight.rs @@ -14,10 +14,10 @@ //! - improve documentation of `#[weight = ..]` and `#[pallet::weight(..)]`. All syntax variation //! should be covered. //! -//! on FRAME benchmarking machinery: +//! On FRAME benchmarking machinery: //! -//! - component analysis, why everything must be linear. -//! - how to write benchmarks, how you must think of worst case. -//! - how to run benchmarks. +//! - Component analysis, why everything must be linear. +//! - How to write benchmarks, how you must think of worst case. +//! - How to run benchmarks. //! //! - diff --git a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs index 9ab7233937f5..f92207143230 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs @@ -43,9 +43,9 @@ //! for example when the encoding of a storage item is changed. However, they can also execute //! arbitrary logic such as: //! -//! - Calling arbitrary pallet methods -//! - Mutating arbitrary on-chain state -//! - Cleaning up some old storage items that are no longer needed +//! - Calling arbitrary pallet methods. +//! - Mutating arbitrary on-chain state. +//! - Cleaning up some old storage items that are no longer needed. //! //! ## Single Block Migrations //! @@ -88,9 +88,9 @@ //! //! Prior to deploying migrations, it is critical to perform additional checks to ensure that when //! run in our real runtime they will not brick the chain due to: -//! - Panicking -//! - Touching too many storage keys and resulting in an excessively large PoV -//! - Taking too long to execute +//! - Panicking. +//! - Touching too many storage keys and resulting in an excessively large PoV. +//! - Taking too long to execute. //! //! [`try-runtime-cli`](https://github.com/paritytech/try-runtime-cli) has a sub-command //! [`on-runtime-upgrade`](https://paritytech.github.io/try-runtime-cli/try_runtime_core/commands/enum.Action.html#variant.OnRuntimeUpgrade) From a816c9cbf7418fe1c0dfe9f60d3036cfd7dacd9c Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:44:32 +0200 Subject: [PATCH 66/86] Can be linked now --- .../reference_docs/frame_runtime_upgrades_and_migrations.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs index f92207143230..065cbee25709 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_upgrades_and_migrations.rs @@ -129,7 +129,9 @@ //! //! Suitable for migrations which could use arbitrary amounts of block weight. //! -//! TODO: Link to multi block migration example/s once PR is merged (). +//! See the +//! [multi-block-migrations example](https://github.com/paritytech/polkadot-sdk/tree/0d7d2177807ec6b3094f4491a45b0bc0d74d3c8b/substrate/frame/examples/multi-block-migrations) +//! for reference. //! //! [`OnRuntimeUpgrade`]: frame_support::traits::OnRuntimeUpgrade //! [`StorageVersion`]: frame_support::traits::StorageVersion From 96e7fd4098dfc1259fa5c83337857fa782cad71f Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:52:31 +0200 Subject: [PATCH 67/86] format --- docs/sdk/src/reference_docs/cli.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/cli.rs b/docs/sdk/src/reference_docs/cli.rs index 5779e0f8d049..b9cdbd60e959 100644 --- a/docs/sdk/src/reference_docs/cli.rs +++ b/docs/sdk/src/reference_docs/cli.rs @@ -45,7 +45,7 @@ //! - `--chain=customSpec.json`: Uses the custom chain specification as input. //! - `--disable-default-bootnode`: Disables the default bootnodes in the node template. //! - `--raw`: Converts the chain specification into a raw format with encoded storage keys. -//! - `> customSpecRaw.json`: Outputs to customSpecRaw.json. +//! - `> customSpecRaw.json`: Outputs to `customSpecRaw.json`. //! //! #### Starting the First Node in a Private Network //! ```bash From 9d8c112caf10149a47462217e2b4b8e2de0ba33f Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:57:19 +0200 Subject: [PATCH 68/86] corrections --- docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs index 83a70606cb8d..c58b2899d15d 100644 --- a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs +++ b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs @@ -1,7 +1,7 @@ //! # Custom RPC do's and don'ts //! -//! **TLDR:** don't create new custom RPCs. Instead, rely on custom Runtime APIs, combined with -//! `state_call` +//! **TLDR:** Don't create new custom RPCs. Instead, rely on custom Runtime APIs, combined with +//! `state_call`. //! //! ## Background //! @@ -20,7 +20,7 @@ //! - To upgrade or add a new RPC logic, the RPC node has to be upgraded. This can cause significant //! trouble when the RPC infrastructure is decentralized as we will need to coordinate multiple //! parties to upgrade the RPC nodes. -//! - A lot of boilerplate code are required to add custom RPC. +//! - A lot of boilerplate code is required to add custom RPC. //! - It prevents the dApp to use a light client or alternative client. //! - It makes ecosystem tooling integration much more complicated. For example, the dApp will not //! be able to use [Chopsticks](https://github.com/AcalaNetwork/chopsticks) for testing as From 90d8a933a4255d2ebc4d809e29f855f8882828c9 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:59:03 +0200 Subject: [PATCH 69/86] not a single dapp --- docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs index c58b2899d15d..07b4109d582d 100644 --- a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs +++ b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs @@ -21,8 +21,8 @@ //! trouble when the RPC infrastructure is decentralized as we will need to coordinate multiple //! parties to upgrade the RPC nodes. //! - A lot of boilerplate code is required to add custom RPC. -//! - It prevents the dApp to use a light client or alternative client. -//! - It makes ecosystem tooling integration much more complicated. For example, the dApp will not +//! - It prevents dApps from using a light client or an alternative client. +//! - It makes ecosystem tooling integration much more complicated. For example, dApps will not //! be able to use [Chopsticks](https://github.com/AcalaNetwork/chopsticks) for testing as //! Chopsticks will not have the custom RPC implementation. //! - Poorly implemented custom RPC can be a DoS vector. From 407fcea4e89c274090f0caa63b9db4984faaa875 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 12:59:50 +0200 Subject: [PATCH 70/86] typo --- docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs index 07b4109d582d..083ed9f77e10 100644 --- a/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs +++ b/docs/sdk/src/reference_docs/custom_runtime_api_rpc.rs @@ -50,7 +50,7 @@ //! //! ## Create a new Runtime API //! -//! For example, let's take a look a the process through which the account nonce can be queried +//! For example, let's take a look at the process through which the account nonce can be queried //! through an RPC. First, a new runtime-api needs to be declared: #![doc = docify::embed!("../../substrate/frame/system/rpc/runtime-api/src/lib.rs", AccountNonceApi)] //! From 6fd6909e7531d29c7bb45acfe39e62ea173f0efe Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:09:41 +0200 Subject: [PATCH 71/86] Add crate and link to it --- Cargo.lock | 1 + docs/sdk/Cargo.toml | 1 + docs/sdk/src/reference_docs/frame_logging.rs | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index 545d20efb16f..48c6fabdeec3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -14546,6 +14546,7 @@ dependencies = [ "frame-support", "frame-system", "kitchensink-runtime", + "log", "minimal-template-runtime", "pallet-asset-conversion-tx-payment", "pallet-asset-tx-payment", diff --git a/docs/sdk/Cargo.toml b/docs/sdk/Cargo.toml index e51fca1e9208..2f85171bb93d 100644 --- a/docs/sdk/Cargo.toml +++ b/docs/sdk/Cargo.toml @@ -40,6 +40,7 @@ frame-support = { workspace = true } frame-executive = { workspace = true } pallet-example-single-block-migrations = { workspace = true, default-features = true } frame-metadata-hash-extension = { workspace = true, default-features = true } +log = { workspace = true, default-features = true } # Substrate Client sc-network = { workspace = true, default-features = true } diff --git a/docs/sdk/src/reference_docs/frame_logging.rs b/docs/sdk/src/reference_docs/frame_logging.rs index 2526bbadde20..1b03c6a2e35b 100644 --- a/docs/sdk/src/reference_docs/frame_logging.rs +++ b/docs/sdk/src/reference_docs/frame_logging.rs @@ -34,7 +34,7 @@ //! //! ## Using `log` //! -//! First, ensure you are familiar with the `log` crate. In short, each log statement has: +//! First, ensure you are familiar with the [`log`] crate. In short, each log statement has: //! //! 1. `log-level`, signifying how important it is. //! 2. `log-target`, signifying to which component it belongs. From aefaee352fe01eb89528ea9a52a73b720ce2122c Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:12:57 +0200 Subject: [PATCH 72/86] typo --- docs/sdk/src/reference_docs/frame_pallet_coupling.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs index 285fc71d9dea..853168fd7e99 100644 --- a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs +++ b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs @@ -110,7 +110,7 @@ //! Crucially, when using loose coupling, we gain the flexibility of providing different //! implementations of `AuthorProvider`, such that different users of a `pallet-foo` can use //! different ones, without any code change being needed. For example, in the code snippets of this -//! module, you can fund [`OtherAuthorProvider`] which is an alternative implementation of +//! module, you can find [`OtherAuthorProvider`], which is an alternative implementation of //! [`AuthorProvider`]. #![doc = docify::embed!("./src/reference_docs/frame_pallet_coupling.rs", other_author_provider)] //! From 165864a744cca00f93a4d72eb924fa91f05d4d01 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:15:31 +0200 Subject: [PATCH 73/86] group is --- docs/sdk/src/reference_docs/frame_pallet_coupling.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs index 853168fd7e99..b75d70375669 100644 --- a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs +++ b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs @@ -135,7 +135,7 @@ //! general, it is easier to argue about multiple pallet if they only communicate together via a //! known trait, rather than having access to all of each others public items, such as storage and //! dispatchables. -//! * If a group of pallets are meant to work together, and but are not foreseen to be generalized, +//! * If a group of pallets is meant to work together, and but are not foreseen to be generalized, //! or used by others, consider tightly coupling pallets, *if it simplifies the development*. //! * If a pallet needs a functionality provided by another pallet, but multiple implementations can //! be foreseen, consider loosely coupling pallets. From 9a1e8a212bf0e201f9f52583f62e0dd1180978d3 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:16:21 +0200 Subject: [PATCH 74/86] messed up sentence --- docs/sdk/src/reference_docs/frame_pallet_coupling.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs index b75d70375669..5202e1418456 100644 --- a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs +++ b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs @@ -135,7 +135,7 @@ //! general, it is easier to argue about multiple pallet if they only communicate together via a //! known trait, rather than having access to all of each others public items, such as storage and //! dispatchables. -//! * If a group of pallets is meant to work together, and but are not foreseen to be generalized, +//! * If a group of pallets is meant to work together, but is not foreseen to be generalized, //! or used by others, consider tightly coupling pallets, *if it simplifies the development*. //! * If a pallet needs a functionality provided by another pallet, but multiple implementations can //! be foreseen, consider loosely coupling pallets. From cd34597575a8914ecfd92bf034db35a34d903167 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:18:27 +0200 Subject: [PATCH 75/86] consistency in lists --- docs/sdk/src/reference_docs/frame_tokens.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_tokens.rs b/docs/sdk/src/reference_docs/frame_tokens.rs index 57b493fafa59..4afb70e08a23 100644 --- a/docs/sdk/src/reference_docs/frame_tokens.rs +++ b/docs/sdk/src/reference_docs/frame_tokens.rs @@ -22,11 +22,11 @@ //! //! On completion of reading this doc, you should have a good understanding of: //! - The distinction between token traits and trait implementations in FRAME, and why this -//! distinction is helpful -//! - Token-related traits available in FRAME -//! - Token-related trait implementations in FRAME -//! - How to choose the right trait or trait implementation for your use case -//! - Where to go next +//! distinction is helpful. +//! - Token-related traits available in FRAME. +//! - Token-related trait implementations in FRAME. +//! - How to choose the right trait or trait implementation for your use case. +//! - Where to go next. //! //! ## Getting Started //! From 7872c5247b9fcc341678b7f640b99586a7e5b1c7 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:27:18 +0200 Subject: [PATCH 76/86] footnote can be used rather --- docs/sdk/src/reference_docs/frame_tokens.rs | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_tokens.rs b/docs/sdk/src/reference_docs/frame_tokens.rs index 4afb70e08a23..c9106e20d382 100644 --- a/docs/sdk/src/reference_docs/frame_tokens.rs +++ b/docs/sdk/src/reference_docs/frame_tokens.rs @@ -56,9 +56,16 @@ //! //! **Trait implementations** are concrete implementations of these traits. For example, one of the //! many traits [`pallet_balances`] implements is -//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`)*. It provides the concrete way +//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`)[^1]. It provides the concrete way //! of inspecting the total issuance, balance of accounts, etc. There can be many implementations of //! the same traits. +//! +//! [^1]: Rust Advanced Tip: The knowledge that [`pallet_balances`] implements +//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`) is not some arcane knowledge +//! that you have to know by heart or memorize. One can simply look at the list of the implementors +//! of any trait in the Rust Doc to find all implementors (e.g. +//! [Mutate trait implementors](https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/trait.Mutate.html#implementors)), +//! or use the `rust-analyzer`'s `Implementations` action. //! //! The distinction between traits and trait implementations is helpful because it allows pallets //! and other logic to be generic over their dependencies, avoiding tight coupling. @@ -81,15 +88,6 @@ //! Read more about coupling, and the benefits of loose coupling //! [here](crate::reference_docs::frame_pallet_coupling). //! -//! ##### *Rust Advanced Tip -//! -//! The knowledge that [`pallet_balances`] implements -//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`) is not some arcane knowledge -//! that you have to know by heart or memorize. One can simply look at the list of the implementors -//! of any trait in the Rust Doc to find all implementors (e.g. -//! ), -//! or use the `rust-analyzer` `Implementations` action. -//! //! ## Fungible Token Traits in FRAME //! //! The [`fungible`](`frame_support::traits::fungible`) crate contains the latest set of FRAME From 25c595746b1f4f54e3244f08e2e4eb40aaa62e43 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:27:29 +0200 Subject: [PATCH 77/86] some punctuation help in this long sentence --- docs/sdk/src/reference_docs/frame_tokens.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sdk/src/reference_docs/frame_tokens.rs b/docs/sdk/src/reference_docs/frame_tokens.rs index c9106e20d382..7b3af14e07d9 100644 --- a/docs/sdk/src/reference_docs/frame_tokens.rs +++ b/docs/sdk/src/reference_docs/frame_tokens.rs @@ -75,9 +75,9 @@ //! pallet may use [`pallet_balances`] in a tightly coupled manner, directly calling methods //! on the pallet to reserve and unreserve deposits. This approach works well, //! until someone has a use case requiring that an asset from a different pallet such as -//! [`pallet_assets`] is used for the deposit. Rather than tightly couple [`pallet_preimage`] to -//! [`pallet_balances`], [`pallet_assets`], and every other token-handling pallet a user -//! could possibly specify, [`pallet_preimage`] does not specify a concrete pallet as a dependency +//! [`pallet_assets`] is used for the deposit. Rather than tightly coupling [`pallet_preimage`] to +//! [`pallet_balances`], [`pallet_assets`], and every other token-handling pallet, a user +//! could possibly specify that [`pallet_preimage`] does not specify a concrete pallet as a dependency, //! but instead accepts any dependency which implements the //! [`currency::ReservableCurrency`](`frame_support::traits::tokens::currency::ReservableCurrency`) //! trait, namely via its [`Config::Currency`](`pallet_preimage::pallet::Config::Currency`) From 5a82fbdebfd8ea9a56c08f8cbc987247728700df Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:40:22 +0200 Subject: [PATCH 78/86] table display was botched --- .../runtime_vs_smart_contract.rs | 21 +++++++------------ 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs b/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs index 379b0c11b2ad..4a0ba3ca48f5 100644 --- a/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs +++ b/docs/sdk/src/reference_docs/runtime_vs_smart_contract.rs @@ -32,21 +32,14 @@ //! //! ## Comparative Table //! -//! | Aspect | Runtime -//! | Smart Contracts | +//! | Aspect | Runtime | Smart Contracts | //! |-----------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------| -//! | **Design Philosophy** | Core logic of a blockchain, allowing broad and deep customization. -//! | Designed for DApps deployed on the blockchain runtime.| | **Development Complexity** | Requires in-depth knowledge of Rust and Substrate. Suitable for complex blockchain architectures. | Easier to develop with knowledge of Smart Contract languages like Solidity or [ink!](https://use.ink/). | -//! | **Upgradeability and Flexibility** | Offers comprehensive upgradeability with migration logic -//! and on-chain governance, allowing modifications to the entire blockchain logic without hard -//! forks. | Less flexible in upgrade migrations but offers more straightforward deployment and -//! iteration. | | **Performance and Efficiency** | More efficient, optimized for specific needs of -//! the blockchain. | Can be less efficient due to its generic nature (e.g. the overhead of a -//! virtual machine). | | **Security Considerations** | Security flaws can affect the entire -//! blockchain. | Security risks usually localized to the individual -//! contract. | | **Weighing and Metering** | Operations can be weighed, allowing for precise -//! benchmarking. | Execution is metered, allowing for measurement of resource -//! consumption. | +//! | **Design Philosophy** | Core logic of a blockchain, allowing broad and deep customization. | Designed for DApps deployed on the blockchain runtime. | +//! | **Development Complexity** | Requires in-depth knowledge of Rust and Substrate. Suitable for complex blockchain architectures. | Easier to develop with knowledge of Smart Contract languages like Solidity or [ink!](https://use.ink/). | +//! | **Upgradeability and Flexibility** | Offers comprehensive upgradeability with migration logic and on-chain governance, allowing modifications to the entire blockchain logic without hard forks. | Less flexible in upgrade migrations but offers more straightforward deployment and iteration. | +//! | **Performance and Efficiency** | More efficient, optimized for specific needs of the blockchain. | Can be less efficient due to its generic nature (e.g. the overhead of a virtual machine). | +//! | **Security Considerations** | Security flaws can affect the entire blockchain. | Security risks usually localized to the individual contract. | +//! | **Weighing and Metering** | Operations can be weighed, allowing for precise benchmarking. | Execution is metered, allowing for measurement of resource consumption. | //! //! We will now explore these differences in more detail. //! From c725a55ce74856abb609d3466cddbc9557e2c1a3 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:46:14 +0200 Subject: [PATCH 79/86] typo? --- docs/sdk/src/reference_docs/frame_runtime_types.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_runtime_types.rs b/docs/sdk/src/reference_docs/frame_runtime_types.rs index 1eed9857a1d5..e99106ade878 100644 --- a/docs/sdk/src/reference_docs/frame_runtime_types.rs +++ b/docs/sdk/src/reference_docs/frame_runtime_types.rs @@ -36,7 +36,7 @@ #![doc = docify::embed!("./src/reference_docs/frame_runtime_types.rs", pallet_bar)] //! //! Let's explore how each of these affect the [`RuntimeCall`], [`RuntimeOrigin`] and -//! [`RuntimeGenesisConfig`] generated in [`runtime`] by respectively. +//! [`RuntimeGenesisConfig`] generated in [`runtime`] respectively. //! //! As observed, [`RuntimeCall`] has 3 variants, one for each pallet and one for `frame_system`. If //! you explore further, you will soon realize that each variant is merely a pointer to the `Call` From f1b890f97f0ad008a49ed312896b650b7c80f1e9 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:50:14 +0200 Subject: [PATCH 80/86] correction --- docs/sdk/src/reference_docs/frame_offchain_workers.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/frame_offchain_workers.rs b/docs/sdk/src/reference_docs/frame_offchain_workers.rs index 1ec9212e2306..b0aaf1789d4c 100644 --- a/docs/sdk/src/reference_docs/frame_offchain_workers.rs +++ b/docs/sdk/src/reference_docs/frame_offchain_workers.rs @@ -88,7 +88,7 @@ //! //! They can both read from the state, and have no means of updating the state, other than the route //! of submitting an extrinsic to the chain. Therefore, it is worth thinking twice before embedding -//! a logic as a part of Substrate's offchain worker API. Does it have to be there? can it not be a +//! a logic as a part of Substrate's offchain worker API. Does it have to be there? Can it not be a //! simple, actual offchain application that lives outside of the chain's WASM blob? //! //! Some of the reasons why you might want to do the opposite, and actually embed an offchain worker From c904ebbde59c9db23c26739eeea553278a7a5b57 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 13:51:59 +0200 Subject: [PATCH 81/86] typo --- docs/sdk/src/reference_docs/wasm_meta_protocol.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs index 0e91e65c55e3..343162c20a98 100644 --- a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs +++ b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs @@ -29,7 +29,7 @@ //! Rust to different hardware targets. //! //! This design enables all Substrate-based chains to be fork-less-ly upgradeable, because the -//! Runtime can be updates on the fly, within the execution of a block, and the node is (for the +//! Runtime can be updated on the fly, within the execution of a block, and the node is (for the //! most part) oblivious to the change that is happening. //! //! Therefore, the high-level architecture of a any Substrate-based chain can be demonstrated as From f2ac2b480f2fb60251607abcd4086fb5a87d8812 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 14:32:25 +0200 Subject: [PATCH 82/86] typo --- docs/sdk/src/reference_docs/wasm_meta_protocol.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs index 343162c20a98..fcdd8704b72d 100644 --- a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs +++ b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs @@ -82,7 +82,7 @@ //! //! ## State //! -//! From the previous sections, we know that the a database component is part of the node, not the +//! From the previous sections, we know that the database component is part of the node, not the //! runtime. We also hinted that a set of host functions ([`sp_io::storage`]) are how the runtime //! issues commands to the node to read/write to the state. Let's dive deeper into this. //! From 2aea4a97fd38988628b08a8318ea4b68bad8293f Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 15:18:21 +0200 Subject: [PATCH 83/86] typos --- docs/sdk/src/reference_docs/wasm_meta_protocol.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs index fcdd8704b72d..55b5cb204dc2 100644 --- a/docs/sdk/src/reference_docs/wasm_meta_protocol.rs +++ b/docs/sdk/src/reference_docs/wasm_meta_protocol.rs @@ -143,13 +143,13 @@ //! At some point, based on the consensus algorithm's rules, the node decides to import (aka. //! *validate*) a block. //! -//! * First, the node will then fetch the state of the parent hash of the block that wishes to be +//! * First, the node will fetch the state of the parent hash of the block that wishes to be //! imported. //! * The runtime is fetched from this state, and placed into a WASM execution environment. -//! * The [`sp_api::Core::execute_block`] runtime API is called and the blocked is passed in as an +//! * The [`sp_api::Core::execute_block`] runtime API is called and the block is passed in as an //! argument. //! * The runtime will then execute the block, and update the state accordingly. Any state update is -//! issues via the [`sp_io::storage`] host functions. +//! issued via the [`sp_io::storage`] host functions. //! * Both the runtime and node will check the state-root of the state after the block execution to //! match the one claimed in the block header. //! From 96f2a64643e1361968f76568be3c29b2bbfc4da8 Mon Sep 17 00:00:00 2001 From: rzadp Date: Fri, 26 Jul 2024 18:43:11 +0200 Subject: [PATCH 84/86] Add note about srtool --- docs/sdk/src/polkadot_sdk/substrate.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index e9edf9d95bda..6c2953493e63 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -87,6 +87,8 @@ //! Substrate-based runtimes use [`substrate_wasm_builder`] in their `build.rs` to automatically //! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the //! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}/{runtime_name}.wasm`. +//! +//! In order to ensure that the WASM build is **deterministic**, the [Substrate Runtime Toolbox (srtool)](https://github.com/paritytech/srtool) can be used. //! //! ### Binaries //! From 37829b8b6e95c0e35c2242fc73a0f9933966c859 Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 29 Jul 2024 14:50:18 +0200 Subject: [PATCH 85/86] markdown lint --- docs/contributor/DOCUMENTATION_GUIDELINES.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/contributor/DOCUMENTATION_GUIDELINES.md b/docs/contributor/DOCUMENTATION_GUIDELINES.md index 79308d22a2a6..cc1082347d20 100644 --- a/docs/contributor/DOCUMENTATION_GUIDELINES.md +++ b/docs/contributor/DOCUMENTATION_GUIDELINES.md @@ -96,10 +96,11 @@ which tests your crate in a different way than unit tests. So, it is both a win You can also consider having an `# Error` section optionally. Of course, this only applies if there is a `Result` being returned, and if the `Error` variants are overly complicated. -Strive to include correct links to other items in your written docs as much as possible. Read more about how to correctly use links in your rust-docs +Strive to include correct links to other items in your written docs as much as possible. +Read more about how to correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and -[here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). In other words, avoid `` `some_func` `` -and instead use ``[`some_func`]``. +[here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax). +In other words, avoid `` `some_func` `` and instead use ``[`some_func`]``. > While you are linking, you might become conscious of the fact that you are in need of linking to (too many) foreign items in order to explain your API. This is leaning more towards API-Design rather than documentation, but it is a From 20d049dbc9ad1e54a386e69beef6ce47a7735b52 Mon Sep 17 00:00:00 2001 From: rzadp Date: Mon, 29 Jul 2024 15:00:59 +0200 Subject: [PATCH 86/86] fmt --- docs/sdk/src/guides/async_backing_guide.rs | 4 ++-- docs/sdk/src/guides/enable_elastic_scaling_mvp.rs | 7 ++++--- docs/sdk/src/guides/mod.rs | 8 ++++---- docs/sdk/src/guides/your_first_pallet/mod.rs | 4 ++-- docs/sdk/src/lib.rs | 4 ++-- docs/sdk/src/polkadot_sdk/mod.rs | 4 ++-- docs/sdk/src/polkadot_sdk/substrate.rs | 8 ++++---- docs/sdk/src/reference_docs/frame_pallet_coupling.rs | 4 ++-- docs/sdk/src/reference_docs/frame_storage_derives.rs | 3 ++- docs/sdk/src/reference_docs/frame_tokens.rs | 12 ++++++------ docs/sdk/src/reference_docs/mod.rs | 9 +++++---- 11 files changed, 35 insertions(+), 32 deletions(-) diff --git a/docs/sdk/src/guides/async_backing_guide.rs b/docs/sdk/src/guides/async_backing_guide.rs index ba3a59c5ce52..a9fda2c3aa8a 100644 --- a/docs/sdk/src/guides/async_backing_guide.rs +++ b/docs/sdk/src/guides/async_backing_guide.rs @@ -27,8 +27,8 @@ //! "scheduling_lookahead": 2 //! ``` //! -//!
scheduling_lookahead must be set to 2, otherwise parachain block times -//! will degrade to worse than with sync backing!
+//!
scheduling_lookahead must be set to 2, otherwise parachain +//! block times will degrade to worse than with sync backing!
//! //! ## Phase 1 - Update Parachain Runtime //! diff --git a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs index 7768b3146e85..939043b53529 100644 --- a/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs +++ b/docs/sdk/src/guides/enable_elastic_scaling_mvp.rs @@ -70,9 +70,10 @@ //! - Ensure enough coretime is assigned to the parachain. For maximum throughput the upper bound is //! 3 cores. //! -//!
Phase 1 is not needed if using the polkadot-parachain binary built -//! from the latest polkadot-sdk release! Simply pass the --experimental-use-slot-based parameter -//! to the command line and jump to Phase 2.
+//!
Phase 1 is not needed if using the polkadot-parachain binary +//! built from the latest polkadot-sdk release! Simply pass the +//! --experimental-use-slot-based parameter to the command line and jump to Phase +//! 2.
//! //! The following steps assume using the cumulus parachain template. //! diff --git a/docs/sdk/src/guides/mod.rs b/docs/sdk/src/guides/mod.rs index 310a6c44de9b..a7fd146ccdf3 100644 --- a/docs/sdk/src/guides/mod.rs +++ b/docs/sdk/src/guides/mod.rs @@ -23,13 +23,13 @@ pub mod your_first_runtime; // TODO // pub mod your_first_node; -// /// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain and connect -// /// it to a relay-chain. +// /// How to enhance a given runtime and node to be cumulus-enabled, run it as a parachain +// /// and connect it to a relay-chain. // TODO // pub mod cumulus_enabled_parachain; -// /// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between itself -// /// and the relay chain to which it is connected. +// /// How to make a given runtime XCM-enabled, capable of sending messages (`Transact`) between +// /// itself and the relay chain to which it is connected. // TODO // pub mod xcm_enabled_parachain; diff --git a/docs/sdk/src/guides/your_first_pallet/mod.rs b/docs/sdk/src/guides/your_first_pallet/mod.rs index 3e52317d4b79..3c74469e1768 100644 --- a/docs/sdk/src/guides/your_first_pallet/mod.rs +++ b/docs/sdk/src/guides/your_first_pallet/mod.rs @@ -45,8 +45,8 @@ //! Consider the following as a "shell pallet". We continue building the rest of this pallet based //! on this template. //! -//! [`pallet::config`] and [`pallet::pallet`](frame_support::pallet) are both mandatory parts of any pallet. Refer to the -//! documentation of each to get an overview of what they do. +//! [`pallet::config`] and [`pallet::pallet`](frame_support::pallet) are both mandatory parts of any +//! pallet. Refer to the documentation of each to get an overview of what they do. #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", shell_pallet)] //! //! All of the code that follows in this guide should live inside of the `mod pallet`. diff --git a/docs/sdk/src/lib.rs b/docs/sdk/src/lib.rs index 1bd318cb5753..bc0970c01f1f 100644 --- a/docs/sdk/src/lib.rs +++ b/docs/sdk/src/lib.rs @@ -13,8 +13,8 @@ //! We suggest the following reading sequence: //! //! - Start by learning about the the [`polkadot_sdk`], its structure and context. -//! - Then, head over to the [`guides`]. This modules contains in-depth guides about the most important -//! user-journeys of the Polkadot SDK. +//! - Then, head over to the [`guides`]. This modules contains in-depth guides about the most +//! important user-journeys of the Polkadot SDK. //! - Whilst reading the guides, you might find back-links to [`reference_docs`]. //! - Finally, is the parent website of this crate that contains the //! list of further tools related to the Polkadot SDK. diff --git a/docs/sdk/src/polkadot_sdk/mod.rs b/docs/sdk/src/polkadot_sdk/mod.rs index 4de6be2bcae1..32cad72fba7e 100644 --- a/docs/sdk/src/polkadot_sdk/mod.rs +++ b/docs/sdk/src/polkadot_sdk/mod.rs @@ -103,8 +103,8 @@ //! //! ## Trophy Section: Notable Downstream Projects //! -//! A list of projects and tools in the blockchain ecosystem that one way or another use parts of the -//! Polkadot SDK: +//! A list of projects and tools in the blockchain ecosystem that one way or another use parts of +//! the Polkadot SDK: //! //! * [Polygon's spin-off, Avail](https://github.com/availproject/avail) //! * [Cardano Partner Chains](https://iohk.io/en/blog/posts/2023/11/03/partner-chains-are-coming-to-cardano/) diff --git a/docs/sdk/src/polkadot_sdk/substrate.rs b/docs/sdk/src/polkadot_sdk/substrate.rs index 6c2953493e63..56b89f8c9c2a 100644 --- a/docs/sdk/src/polkadot_sdk/substrate.rs +++ b/docs/sdk/src/polkadot_sdk/substrate.rs @@ -63,9 +63,9 @@ //! categories: //! //! * `sc-*` (short for *Substrate-client*) crates, located under `./client` folder. These are all -//! the crates that lead to the node software. Notable examples are [`sc_network`], various consensus -//! crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are expected to -//! reside in the node side. +//! the crates that lead to the node software. Notable examples are [`sc_network`], various +//! consensus crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are +//! expected to reside in the node side. //! * `sp-*` (short for *substrate-primitives*) crates, located under `./primitives` folder. These //! are crates that facilitate both the node and the runtime, but are not opinionated about what //! framework is using for building the runtime. Notable examples are [`sp_api`] and [`sp_io`], @@ -87,7 +87,7 @@ //! Substrate-based runtimes use [`substrate_wasm_builder`] in their `build.rs` to automatically //! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the //! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}/{runtime_name}.wasm`. -//! +//! //! In order to ensure that the WASM build is **deterministic**, the [Substrate Runtime Toolbox (srtool)](https://github.com/paritytech/srtool) can be used. //! //! ### Binaries diff --git a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs index 5202e1418456..a22137f979dc 100644 --- a/docs/sdk/src/reference_docs/frame_pallet_coupling.rs +++ b/docs/sdk/src/reference_docs/frame_pallet_coupling.rs @@ -135,8 +135,8 @@ //! general, it is easier to argue about multiple pallet if they only communicate together via a //! known trait, rather than having access to all of each others public items, such as storage and //! dispatchables. -//! * If a group of pallets is meant to work together, but is not foreseen to be generalized, -//! or used by others, consider tightly coupling pallets, *if it simplifies the development*. +//! * If a group of pallets is meant to work together, but is not foreseen to be generalized, or +//! used by others, consider tightly coupling pallets, *if it simplifies the development*. //! * If a pallet needs a functionality provided by another pallet, but multiple implementations can //! be foreseen, consider loosely coupling pallets. //! diff --git a/docs/sdk/src/reference_docs/frame_storage_derives.rs b/docs/sdk/src/reference_docs/frame_storage_derives.rs index 359d073b63c3..4fbfb4a5cc83 100644 --- a/docs/sdk/src/reference_docs/frame_storage_derives.rs +++ b/docs/sdk/src/reference_docs/frame_storage_derives.rs @@ -2,7 +2,8 @@ //! //! > **Note:** //! > -//! > In all examples, a few lines of boilerplate have been hidden from each snippet for conciseness. +//! > In all examples, a few lines of boilerplate have been hidden from each snippet for +//! > conciseness. //! //! Let's begin by starting to store a `NewType` in a storage item: //! diff --git a/docs/sdk/src/reference_docs/frame_tokens.rs b/docs/sdk/src/reference_docs/frame_tokens.rs index 7b3af14e07d9..a76e524ceb85 100644 --- a/docs/sdk/src/reference_docs/frame_tokens.rs +++ b/docs/sdk/src/reference_docs/frame_tokens.rs @@ -56,10 +56,10 @@ //! //! **Trait implementations** are concrete implementations of these traits. For example, one of the //! many traits [`pallet_balances`] implements is -//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`)[^1]. It provides the concrete way -//! of inspecting the total issuance, balance of accounts, etc. There can be many implementations of -//! the same traits. -//! +//! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`)[^1]. It provides the concrete +//! way of inspecting the total issuance, balance of accounts, etc. There can be many +//! implementations of the same traits. +//! //! [^1]: Rust Advanced Tip: The knowledge that [`pallet_balances`] implements //! [`fungible::Inspect`](`frame_support::traits::fungible::Inspect`) is not some arcane knowledge //! that you have to know by heart or memorize. One can simply look at the list of the implementors @@ -77,8 +77,8 @@ //! until someone has a use case requiring that an asset from a different pallet such as //! [`pallet_assets`] is used for the deposit. Rather than tightly coupling [`pallet_preimage`] to //! [`pallet_balances`], [`pallet_assets`], and every other token-handling pallet, a user -//! could possibly specify that [`pallet_preimage`] does not specify a concrete pallet as a dependency, -//! but instead accepts any dependency which implements the +//! could possibly specify that [`pallet_preimage`] does not specify a concrete pallet as a +//! dependency, but instead accepts any dependency which implements the //! [`currency::ReservableCurrency`](`frame_support::traits::tokens::currency::ReservableCurrency`) //! trait, namely via its [`Config::Currency`](`pallet_preimage::pallet::Config::Currency`) //! associated type. This allows [`pallet_preimage`] to support any arbitrary pallet implementing diff --git a/docs/sdk/src/reference_docs/mod.rs b/docs/sdk/src/reference_docs/mod.rs index 04a05837c5ef..7f2edb08d46e 100644 --- a/docs/sdk/src/reference_docs/mod.rs +++ b/docs/sdk/src/reference_docs/mod.rs @@ -7,10 +7,11 @@ //! //! ## What is a "reference document"? //! -//! First, see [why we use rust-docs for everything](crate::meta_contributing#why-rust-docs) and our documentation -//! [principles](crate::meta_contributing#principles). We acknowledge that as much of the crucial information should be -//! embedded in the low level rust-docs. Then, high level scenarios should be covered in -//! [`crate::guides`]. Finally, we acknowledge that there is a category of information that is: +//! First, see [why we use rust-docs for everything](crate::meta_contributing#why-rust-docs) and our +//! documentation [principles](crate::meta_contributing#principles). We acknowledge that as much of +//! the crucial information should be embedded in the low level rust-docs. Then, high level +//! scenarios should be covered in [`crate::guides`]. Finally, we acknowledge that there is a +//! category of information that is: //! //! 1. Crucial to know. //! 2. Is too high level to be in the rust-doc of any one `type`, `trait` or `fn`.