Add missing glossary to ref docs

developer-hub/src/lib.rs

@@ -35,16 +35,16 @@
 //! it externally extremely difficult, especially with regards to making sure it is up-to-date.
 //!
 //! Consequently, we argue that the best hedge against this is to move as much of the documentation
-//! near the source code as possible. This would further incentivizes developers to keep the
+//! near the source code as possible. This would further incentivize developers to keep the
 //! 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
-//! > `md-book`) cannot exist, but it would be the outside the scope of this crate.
+//! > `md-book`) cannot exist, but it would be outside the scope of this crate.
 //!
-//! Moreover, we acknowledge that a major pain-pint has been not only outdated *concepts*, but also
+//! Moreover, we acknowledge that a major pain point has been not only outdated *concepts*, but also
 //! *outdated code*. For this, we commit to making sure no code-snippet in this crate is left as
-//! `///ignore` or `///no_compile``, making sure all code snippets are self-contained, compile-able,
+//! `///ignore` or `///no_compile`, making sure all code snippets are self-contained, compile-able,
 //! and correct at every single revision of the entire repository.
 //!
 //! > This also allows us to have a clear versioning on the entire content of this crate. For every
@@ -69,9 +69,9 @@
 //! crate.
 //!
 //! 1. 🔺 Ground Up: Information should be layed out in the most ground-up fashion. The lowest level
-//!    (ie. "ground") is Rust-docs. The highest level (ie "up") is "outside of this crate". In
+//!    (i.e. "ground") is Rust-docs. The highest level (i.e. "up") is "outside of this crate". In
 //!    between lies [`reference_docs`] and [`tutorial`], from low to high. The point of this
-//!    principle is to document as much of the information is possible in the lower lever media, as
+//!    principle is to document as much of the information as possible in the lower level media, as
 //!    it is easier to maintain and more reachable. Then, use excessive linking to back-link when
 //!    writing in a more high level.
 //!
@@ -88,7 +88,7 @@
 //!
 //! > A prime example of this, the list of CLI arguments of a particular binary should not be
 //! > documented in multiple places across this crate. It should be only be documented in the
-//! > corresponding crate (eg. `sc_cli`).
+//! > corresponding crate (e.g. `sc_cli`).
 //!
 //! > Moreover, this means that as a contributor, **it is your responsibility to have a grasp over
 //! > what topics are already covered in this crate, and how you can build on top of the information
@@ -130,17 +130,17 @@
 //! [`reference_docs::trait_based_programming`].
 //! * First, the name. Why is this called `pallet::call`? This goes back to `enum Call`, which is
 //! explained in [`reference_docs::frame_composite_enums`]. Build on top of this!
-//! * Then, what is origin? Just an account id? [`reference_docs::frame_origin`].
-//! * Then, what is `DispatchResult`? why is this called *dispatch*? Probably something that can be
+//! * Then, what is `origin`? Just an account id? [`reference_docs::frame_origin`].
+//! * Then, what is `DispatchResult`? Why is this called *dispatch*? Probably something that can be
 //! explained in the documentation of [`frame::prelude::DispatchResult`].
-//! * Why is `"SomeStaticString"` a valid error? because of
-//!   [this](frame::prelude::DispatchError#impl-From<%26'static+str>-for-DispatchError).
+//! * Why is `"SomeStaticString"` a valid error? Because there is implementation for it that you can
+//!   see [here](frame::prelude::DispatchError#impl-From<%26'static+str>-for-DispatchError).
 //!
 //!
 //! All of these are examples of underlying information that a contributor should:
 //!
-//! 1. try and create and they are going along.
-//! 2. back-link to if they already exist.
+//! 1. Try and create and they are going along.
+//! 2. Back-link to if they already exist.
 //!
 //! Of course, all of this is not set in stone as a either/or rule. Sometimes, it is necessary to
 //! rephrase a concept in a new context.

developer-hub/src/polkadot_sdk/cumulus.rs

@@ -8,8 +8,8 @@
 //!
 //! ## Example: Runtime
 //!
-//! A cumulus based runtime is fairly similar to a normal [FRAME]-based runtime. Most notably, the
-//! following changes are applied to a normal FRAME-based runtime to make it a cumulus-based
+//! A Cumulus-based runtime is fairly similar to other [FRAME]-based runtimes. Most notably, the
+//! following changes are applied to a normal FRAME-based runtime to make it a Cumulus-based
 //! runtime:
 //!
 //! #### Cumulus Pallets
@@ -21,7 +21,7 @@
 //! - [`parachain-info`]
 #![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", system_pallets)]
 //!
-//! Given that all cumulus-based runtimes use a simple aura-based consensus mechanism, the following
+//! Given that all Cumulus-based runtimes use a simple Aura-based consensus mechanism, the following
 //! pallets also need to be added:
 //!
 //! - [`pallet-timestamp`]
@@ -30,9 +30,10 @@
 // #![doc = docify::embed!("./src/lib.rs", consensus_pallets)]
 //!
 //!
-//! Finally, a separate macro, similar to `impl_runtime_api`, which create the default set of
-//! runtime apis, will generate the parachain runtime's main additional runtime api, also known as
-//! PVF.
+//! Finally, a separate macro, similar to `impl_runtime_api`, which creates the default set of
+//! runtime APIs, will generate the parachain runtime's validation runtime API, also known as
+//! parachain validation function (PVF). Without this API, the relay chain is unable to validate blocks
+//! produced by our parachain.
 #![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", validate_block)]
 //!
 //!

developer-hub/src/polkadot_sdk/frame_runtime.rs

@@ -15,8 +15,7 @@
 //!
 //! ## Introduction
 //!
-//! recall from [`crate::reference_docs::wasm_meta_protocol`] that at a very high, a substrate-based
-//! blockchain is made with it is composed of two parts:
+//! As described in [`crate::reference_docs::wasm_meta_protocol`], at a high-level substrate-based blockchains are composed of two parts:
 //!
 //! 1. A *runtime* which represents the state transition function (i.e. "Business Logic") of a
 //! blockchain, and is encoded as a Wasm blob.
@@ -46,7 +45,7 @@
 //! - [Errors](frame::pallet_macros::error), allowing a pallet to emit well-formed errors.
 //!
 //! Most of these components are defined using macros, the full list of which can be found in
-//! [`frame::pallet_macros`]
+//! [`frame::pallet_macros`].
 //!
 //! ### Example
 //!
@@ -71,7 +70,7 @@
 //!
 //! ## More Examples
 //!
-//! You can find more FRAME examples that revolve around specific features at [`pallet_examples`]
+//! You can find more FRAME examples that revolve around specific features at [`pallet_examples`].
 
 #[cfg(test)]
 mod tests {

developer-hub/src/polkadot_sdk/mod.rs

@@ -20,10 +20,10 @@
 //! The primary way to get started with the Polkadot SDK is to start writing a Substrate-based
 //! runtime using FRAME. See:
 //!
-//! 0. [`polkadot`], to understand what is Polkadot as a development platform.
-//! 1. [`substrate`], for an overview of what Substrate is.
-//! 2. Jump right into [`frame`] to learn about how to write a FRAME-based blockchain runtime.
-//! 3. Continue with the [`developer_hub`'s "getting started"](crate#getting-started).
+//! * [`polkadot`], to understand what is Polkadot as a development platform.
+//! * [`substrate`], for an overview of what Substrate is.
+//! * Jump right into [`frame`] to learn about how to write a FRAME-based blockchain runtime.
+//! * Continue with the [`developer_hub`'s "getting started"](crate#getting-started).
 //!
 //! ## Structure
 //!
@@ -50,15 +50,15 @@
 //! [![GitHub Repo](https://img.shields.io/badge/github-cumulus-white)](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus)
 //!
 //! [`cumulus`] transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and
-//! substrate-based client into Polkadot-compatible collators.
+//! Substrate-based clients into Polkadot-compatible collators.
 //!
 //! #### Polkadot
 //!
 //! [![Polkadot-license](https://img.shields.io/badge/License-GPL3-blue)](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
 //! [![GitHub Repo](https://img.shields.io/badge/github-polkadot-e6007a?logo=polkadot)](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot)
 //!
 //! [`polkadot`] is an implementation of a Polkadot client in Rust, by `@paritytech`. The Polkadot
-//! runtimes are located under the [`fellowship/runtime`](https://github.com/polkadot-fellows/runtimes) repository.
+//! runtimes are located under the [`polkadot-fellows/runtimes`](https://github.com/polkadot-fellows/runtimes) repository.
 //!
 //! > [`polkadot`] contains useful links to further learn about Polkadot, **but is in general not
 //! > part of the SDK**, as it is rarely used by developers who wish to build on top of Polkadot.
@@ -81,7 +81,7 @@
 //!    everything else. 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 Substrate client
 //!    libraries.
-//! 2. Polkadot is itself a Substrate-based chain, composed of the the exact same two components.
+//! 2. Polkadot is itself a Substrate-based chain, composed of the exact same two components.
 //!    The Polkadot client code is in [`polkadot`], and the Polkadot runtimes are controlled by the
 //!    [Polkadot Fellowship](https://github.com/polkadot-fellows).
 //! 3. A parachain is a "special" Substrate based chain, whereby both the client and the runtime
@@ -95,7 +95,7 @@
 //! - <https://polkadot-public.notion.site/Polkadot-SDK-FAQ-fbc4cecc2c46443fb37b9eeec2f0d85f>
 //! - <https://forum.polkadot.network/t/psa-parity-is-currently-working-on-merging-the-polkadot-stack-repositories-into-one-single-repository/2883>
 //!
-//! ## Notable Upstream Crates:
+//! ## Notable Upstream Crates
 //!
 //! - [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec)
 //! - [`parity-db`](https://github.com/paritytech/parity-db)

developer-hub/src/polkadot_sdk/polkadot.rs

@@ -28,13 +28,13 @@
 //! Polkadot's answer to the above is:
 //!
 //! * Shared Security: The idea of shared economic security sits at the core of Polkadot. Polkadot
-//!   enables different blockchains (ie. "*Parachains*") to pool their economic security from
-//!   Polkadot (ie. "*Relay Chain*").
+//!   enables different blockchains (i.e. "*Parachains*") to pool their economic security from
+//!   Polkadot (i.e. "*Relay Chain*").
 //! * A framework to build blockchains: In order to materialize the multi-chain future, an easy
-//!   blockchain framework must exist. This is [`crate::polkadot_sdk::substrate`],
-//!   [`crate::polkadot_sdk::frame_runtime`] and [`crate::polkadot_sdk::cumulus`].
+//!   blockchain framework must exist. This is [Substrate](crate::polkadot_sdk::substrate),
+//!   [FRAME](crate::polkadot_sdk::frame_runtime) and [Cumulus](crate::polkadot_sdk::cumulus).
 //! * A communication language between blockchains: In order for these blockchains to communicate,
-//!   they need a shared language. [`crate::polkadot_sdk::xcm`] is one such language.
+//!   they need a shared language. [XCM](crate::polkadot_sdk::xcm) is one such language.
 //!
 //! > Note that the interoperability promised by Polkadot is unparalleled in that any two parachains
 //! > connected to Polkadot have the same security and can have much higher guarantees about the
@@ -43,10 +43,10 @@
 //! Polkadot delivers the above vision, alongside a flexible means for parachains to schedule
 //! themselves with the Relay Chain. To achieve this, Polkadot has been developed with an
 //! architecture similar to that of a computer. Polkadot Relay Chain has a number of "cores". Each
-//! is (in simple terms) is capable of progressing 1 parachain a a time. For example, a parachain
-//! can schedule itself for on a single core for 5 blocks.
+//! is (in simple terms) capable of progressing 1 parachain at a time. For example, a parachain
+//! can schedule itself on a single core for 5 blocks.
 //!
-//! Within the scope of Polkadot 1.x, two main scheduling ways has been considered:
+//! 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.

developer-hub/src/polkadot_sdk/substrate.rs

@@ -13,9 +13,9 @@
 //!
 //! 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 achieve this goal, Substrate embraces the following:
 //!
-//! 1. Use of **Rust** as a modern, and safe programming language, which limits human error through
+//! 1. Use of **Rust** as a modern and safe programming language, which limits human error through
 //!    various means, most notably memory and type safety.
 //! 2. Substrate is written from the ground-up with a *generic, modular and extensible* design. This
 //!    ensures that software components can be easily swapped and upgraded. Examples of this is
@@ -29,7 +29,7 @@
 //! 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
 //! 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
+//! same as updating an account's balance. Learn more about this in detail in
 //! [`crate::reference_docs::wasm_meta_protocol`].
 //!
 //! [`frame`], Substrate's default runtime development library, takes the above safety practices
@@ -39,10 +39,10 @@
 //!
 //! ## How to Get Stared
 //!
-//! While most developer develop using [`crate::polkadot_sdk::frame_runtime`], it is worth noting a
+//! While most developers use [`crate::polkadot_sdk::frame_runtime`], it is worth noting a
 //! few (niche) alternatives:
 //!
-//! 1.It is entirely possible to craft a substrate-based runtime without FRAME, an example of which
+//! 1. It is entirely possible to craft a substrate-based runtime without FRAME, an example of which
 //! can be found [here](https://github.com/JoshOrndorff/frameless-node-template).
 //! 2. Substrate's client side code, as mentioned above, is also highly configurable, and many teams
 //!    embark on customizing the client, for example with a custom consensus algorithm. Notable
@@ -51,7 +51,7 @@
 //! - <https://github.com/Cardinal-Cryptography/aleph-node>
 //! - <https://github.com/availproject/avail>
 //!
-//! 3. A number of substrate-based templates are listed in [`crate::polkadot_sdk::templates`].
+//! 3. A number of Substrate-based templates are listed in [`crate::polkadot_sdk::templates`].
 //!
 //! ## Structure
 //!

developer-hub/src/reference_docs/wasm_meta_protocol.rs

@@ -3,7 +3,7 @@
 //! All Substrate based chains adhere to a unique architectural design novel to the Polkadot
 //! ecosystem. We refer to this design as the "WASM Meta Protocol".
 //!
-//! Consider the fact that a traditional blockchain software is usually a monolith artifact.
+//! Consider the fact that a traditional blockchain software is usually a monolithic artifact.
 //! Upgrading any part of the system implies upgrading the entire system. This has historically led
 //! to cumbersome forkful upgrades to be the status quo in the blockchain ecosystem.
 //!
@@ -13,7 +13,7 @@
 //! Substrate mixes these two ideas together, and takes the novel approach of storing the
 //! blockchain's main "state transition function" in the main blockchain state, the same fashion
 //! that a smart contract platform stores the code of individual contracts in its state. As noted in
-//! [`crate::reference_docs::blockchain_state_machines`], This state transition function is called
+//! [`crate::reference_docs::blockchain_state_machines`], this state transition function is called
 //! the **Runtime**, and WASM is chosen as the bytecode. The Runtime is stored under a special key
 //! in the state (see [`sp_core::storage::well_known_keys`]), and can be updated as a part of the
 //! state transition function's execution, just like a user's account balance can be updated.

docs/mermaid/polkadot_sdk.mmd

@@ -5,21 +5,21 @@ flowchart LR
     end
 
     subgraph Polkadot[The Polkadot Relay Chain]
-        PolkadotClinet[Polkadot Clinet]
+        PolkadotClient[Polkadot Client]
         PolkadotRuntime[Polkadot Runtime]
     end
 
     subgraph SubstrateChain[A Substrate-based blockchain]
-        Clinet
+        Client
         Runtime
     end
 
     FRAME1[FRAME] -.-> Runtime
     FRAME2[FRAME] -.-> PolkadotRuntime
     FRAME3[FRAME] -.-> ParachainRuntime
 
-    Substrate1[Substrate Client Libraries] -.-> Clinet
-    Substrate2[Substrate Client Libraries] -.-> PolkadotClinet
+    Substrate1[Substrate Client Libraries] -.-> Client
+    Substrate2[Substrate Client Libraries] -.-> PolkadotClient
     Substrate3[Substrate Client Libraries] -.-> ParachainCollator
 
     Cumulus1[Cumulus Runtime Pallets/Libraries] -.-> ParachainRuntime

docs/mermaid/state.mmd

@@ -1,13 +1,13 @@
 flowchart TB
-    subgraph Client[Client's Vew Of The State 🙈]
+    subgraph Client[Client's View Of The State 🙈]
         direction LR
         0x1234 --> 0x2345
         0x3456 --> 0x4567
         0x5678 --> 0x6789
         :code --> code[wasm code]
     end
 
-    subgraph Runtime[Runtime's Vew Of The State 🙉]
+    subgraph Runtime[Runtime's View Of The State 🙉]
         direction LR
         ab[alice's balance] --> abv[known value]
         bb[bob's balance] --> bbv[known value]

substrate/frame/support/procedural/src/pallet/parse/call.rs

@@ -168,7 +168,7 @@ pub fn check_dispatchable_first_arg_type(ty: &syn::Type) -> syn::Result<()> {
 		.map(|_| ())
 		.or_else(|_| syn::parse2::<CheckRuntimeOrigin>(ty.to_token_stream()).map(|_| ()))
 		.map_err(|e| {
-			let msg = "Invalid type: expected `OriginFor<T>`";
+			let msg = "Invalid type: expected `OriginFor<T>` or `T::RuntimeOrigin`";
 			let mut err = syn::Error::new(ty.span(), msg);
 			err.combine(e);
 			err