Skip to content

Commit

Permalink
Various corrections in the documentation (paritytech#5154)
Browse files Browse the repository at this point in the history
An attempt to improve [the
docs](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html)
by applying various corrections:

- grammar/stylistics,
- formatting,
- broken links,
- broken markdown table,
- outdated vscode setting name,
- typos,
- consistency,
- etc.

Part of paritytech/eng-automation#10
  • Loading branch information
rzadp authored and TarekkMA committed Aug 2, 2024
1 parent bbbd816 commit f104abc
Show file tree
Hide file tree
Showing 36 changed files with 177 additions and 166 deletions.
5 changes: 5 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

21 changes: 10 additions & 11 deletions docs/contributor/DOCUMENTATION_GUIDELINES.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -88,20 +88,19 @@ 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` ``
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
Expand Down Expand Up @@ -145,7 +144,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.
Expand Down Expand Up @@ -272,7 +271,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`.

Expand Down
5 changes: 5 additions & 0 deletions docs/sdk/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down Expand Up @@ -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 }
Expand Down
4 changes: 2 additions & 2 deletions docs/sdk/src/guides/async_backing_guide.rs
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@
//! "scheduling_lookahead": 2
//! ```
//!
//! <div class="warning">`scheduling_lookahead` must be set to 2, otherwise parachain block times
//! will degrade to worse than with sync backing!</div>
//! <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
//!
Expand Down
9 changes: 5 additions & 4 deletions docs/sdk/src/guides/enable_elastic_scaling_mvp.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -70,9 +70,10 @@
//! - 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
//! to the command line and jump to Phase 2.</div>
//! <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.
//!
Expand Down
6 changes: 3 additions & 3 deletions docs/sdk/src/guides/enable_metadata_hash.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/sdk/src/guides/enable_pov_reclaim.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down
12 changes: 6 additions & 6 deletions docs/sdk/src/guides/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
16 changes: 8 additions & 8 deletions docs/sdk/src/guides/your_first_pallet/mod.rs
Original file line number Diff line number Diff line change
@@ -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:
//!
Expand All @@ -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.
Expand All @@ -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`] 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`.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
//!
Expand Down
6 changes: 3 additions & 3 deletions docs/sdk/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 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, <https://paritytech.github.io> is the parent website of this crate that contains the
//! list of further tools related to the Polkadot SDK.
Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/sdk/src/meta_contributing.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/sdk/src/polkadot_sdk/frame_runtime.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
//!
//!
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>;
Expand Down
12 changes: 6 additions & 6 deletions docs/sdk/src/polkadot_sdk/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -103,8 +103,8 @@
//!
//! ## Trophy Section: Notable Downstream Projects
//!
//! A list of projects and tools in the blockchain ecosystem that one way or another 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/)
Expand All @@ -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.
Expand Down
Loading

0 comments on commit f104abc

Please sign in to comment.