Various corrections in the documentation

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.
@@ -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
@@ -88,19 +88,17 @@ 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
-test coverage. As an additional benefit, any code in rust-docs is treated as an "integration tests", not unit tests,
+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",
 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".
 
 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
@@ -145,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.
 
@@ -272,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`.
 

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 }
@@ -107,7 +108,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 }

docs/sdk/src/guides/async_backing_guide.rs

@@ -27,7 +27,7 @@
 //! "scheduling_lookahead": 2
 //! ```
 //!
-//! <div class="warning">`scheduling_lookahead` must be set to 2, otherwise parachain block times
+//! <div class="warning"><code>scheduling_lookahead</code> must be set to 2, otherwise parachain block times
 //! will degrade to worse than with sync backing!</div>
 //!
 //! ## Phase 1 - Update Parachain Runtime

docs/sdk/src/guides/enable_elastic_scaling_mvp.rs

@@ -1,7 +1,7 @@
 //! # Enable elastic scaling MVP for a parachain
 //!
 //! <div class="warning">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 <a href="https://wiki.polkadot.network/docs/maintain-guides-async-backing">the Polkadot Wiki</a>.
 //! Furthermore, the parachain should have already been upgraded according to the guide.</div>
 //!
 //! ## Quick introduction to elastic scaling
@@ -70,8 +70,8 @@
 //! - Ensure enough coretime is assigned to the parachain. For maximum throughput the upper bound is
 //!   3 cores.
 //!
-//! <div class="warning">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
+//! <div class="warning">Phase 1 is not needed if using the <code>polkadot-parachain</code> binary built
+//! from the latest polkadot-sdk release! Simply pass the <code>--experimental-use-slot-based</code> parameter
 //! to the command line and jump to Phase 2.</div>
 //!
 //! The following steps assume using the cumulus parachain template.

docs/sdk/src/guides/enable_metadata_hash.rs

@@ -16,15 +16,15 @@
 //! 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,
 //! 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

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

docs/sdk/src/guides/mod.rs

@@ -15,21 +15,21 @@
 /// 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;
 
-/// 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;
 

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:
 //!
@@ -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.
@@ -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)]
 //!
@@ -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
@@ -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<T::AccountId, _>`. 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
@@ -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
@@ -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
 //!

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, <https://paritytech.github.io> is the parent website of this crate that contains the
@@ -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.

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

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)]
 //!
 //!
@@ -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
@@ -119,11 +119,11 @@ pub mod pallet {
 	#[pallet::pallet]
 	pub struct Pallet<T>(PhantomData<T>);
 
-	/// The events tha this pallet can emit.
+	/// The events that this pallet can emit.
 	#[pallet::event]
 	pub enum Event<T: Config> {}
 
-	/// 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<T> = StorageValue<Value = u32>;

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
 //!
@@ -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
@@ -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.
@@ -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)
@@ -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.