pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-06-09 20:11:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

Markdown linter (#1309)

Browse Source 
* Add markdown linting

- add linter default rules
- adapt rules to current code
- fix the code for linting to pass
- add CI check

fix #1243

* Fix markdown for Substrate
* Fix tooling install
* Fix workflow
* Add documentation
* Remove trailing spaces
* Update .github/.markdownlint.yaml

Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Fix mangled markdown/lists
* Fix captalization issues on known words
This commit is contained in:
Chevdor
2023-09-04 11:02:32 +02:00
committed by GitHub
parent 830fde2a60
commit a30092ab42
271 changed files with 6289 additions and 4450 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CONTRIBUTING.md
+9 -9
View File
@@ -32,11 +32,11 @@ If it is an urgent fix with no large change to logic, then it may be merged afte
contributor has reviewed it well and approved the review once CI is complete.
No PR should be merged until all reviews' comments are addressed.
### Labels:
### Labels
The set of labels and their description can be found [here](https://paritytech.github.io/labels/doc_polkadot-sdk.html).
### Process:
### Process
1. Please use our [Pull Request Template](./PULL_REQUEST_TEMPLATE.md) and make sure all relevant
information is reflected in your PR.
@@ -50,12 +50,12 @@ The set of labels and their description can be found [here](https://paritytech.g
`T13-documentation`. The docs team will get in touch.
5. If your PR changes files in these paths:
`polkadot` : '^runtime/polkadot'
`polkadot` : '^runtime/kusama'
`polkadot` : '^primitives/src/'
`polkadot` : '^runtime/common'
`substrate` : '^frame/'
`substrate` : '^primitives/'
`polkadot` : `^runtime/polkadot`
`polkadot` : `^runtime/kusama`
`polkadot` : `^primitives/src/`
`polkadot` : `^runtime/common`
`substrate` : `^frame/`
`substrate` : `^primitives/`
It should be added to the [security audit board](https://github.com/orgs/paritytech/projects/103)
and will need to undergo an audit before merge.
@@ -67,7 +67,7 @@ to change the code to make it work/compile.
It should also mention potential storage migrations and if they require some special setup aside adding
it to the list of migrations in the runtime.
## Reviewing pull requests:
## Reviewing pull requests
When reviewing a pull request, the end-goal is to suggest useful changes to the author.
Reviews should finish with approval unless there are issues that would result in:
docs/DOCUMENTATION_GUIDELINE.md
+109 -124
View File
@@ -1,11 +1,10 @@
# 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.
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.
These crates are used by external developers and need thorough documentation.
They are the most concerned with FRAME development.
These crates are used by external developers and need thorough documentation. They are the most concerned with FRAME
development.
- [Substrate Documentation Guidelines](#substrate-documentation-guidelines)
- [General/Non-Pallet Crates](#generalnon-pallet-crates)
@@ -35,22 +34,19 @@ 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),
2. All `pub` items need to be documented. If not `pub`, it doesn't appear in the
rust-docs, and is not public facing.
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 this won't be used by anyone else.
These need **not** be documented thoroughly.
- Within `pub` items, sometimes they are only `pub` to be used by another internal crate, and you can foresee that
this won't be used by anyone else. These need **not** be documented thoroughly.
* Reminder: `trait` items are public by definition if the trait is public.
- Reminder: `trait` items are public by definition if the trait is public.
3. All public modules (`mod`) should have reasonable module-level documentation (`//!`).
#### Rust Docs vs. Code Comments
Note that anything starting with `///` is an external rust-doc, and everything
starting with `//` does not appear in the rust-docs.
It's important to not confuse the two in your documentation.
Note that anything starting with `///` is an external rust-doc, and everything starting with `//` does not appear in the
rust-docs. It's important to not confuse the two in your documentation.
```rust
/// Computes the square root of the input, returning `Ok(_)` if successful.
@@ -73,100 +69,88 @@ pub fn sqrt(x: u32) -> Result<u32, ()> {
There are good sources to look into:
- [Rust Documentation Guide](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html)
- [Documentation in Rust Book](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments)
- [Guide on Writing Documentation for a Rust Crate](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate)
- [Documentation in Rust
Book](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments)
- [Guide on Writing Documentation for a Rust
Crate](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate)
As mentioned [here](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#writing-documentation-comments) and [here](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate),
always start with a **single sentence** demonstrating what is documented. All additional
documentation should be added *after a newline*. Strive to make the first sentence succinct
and short.The reason for this is the first paragraph of docs about an item (everything
before the first newline) is used as the excerpt that rust doc displays about
this item when it appears in tables, such as the table listing all functions in
a module. If this excerpt is too long, the module docs will be very difficult
to read.
As mentioned
[here](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#writing-documentation-comments)
and [here](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate),
always start with a **single sentence** demonstrating what is documented. All additional documentation should be added
*after a newline*. Strive to make the first sentence succinct and short.The reason for this is the first paragraph of
docs about an item (everything before the first newline) is used as the excerpt that rust doc displays about this item
when it appears in tables, such as the table listing all functions in a module. If this excerpt is too long, the module
docs will be very difficult to read.
About [special sections](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#special-sections), 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.
About [special
sections](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#special-sections),
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, 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".
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".
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.
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
[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`]``.
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
[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`]``.
> 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
warning that the subject API might be slightly wrong. For example, most "glue"
traits[^1] in `frame/support` should be designed and documented without making
hard assumptions about particular pallets that implement them.
> 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
warning that the subject API might be slightly wrong. For example, most "glue" traits[^1] in `frame/support` should be
designed and documented without making hard assumptions about particular pallets that implement them.
---
#### TLDR
0. Have the goal of enforcing `#![deny(missing_docs)]` mentally, even if it is
not enforced by the compiler 🙈.
1. Start with a single, clear and concise sentence. Follow up with more context,
after a newline, if needed.
0. Have the goal of enforcing `#![deny(missing_docs)]` mentally, even if it is not enforced by the compiler 🙈.
1. Start with a single, clear and concise sentence. Follow up with more context, after a newline, if needed.
2. Use examples as much as reasonably possible.
3. Use links as much as possible.
4. Think about context. If you are explaining a lot of foreign topics while
documenting a trait that should not explicitly depend on them, you have likely
not designed it properly.
4. Think about context. If you are explaining a lot of foreign topics while documenting a trait that should not
explicitly depend on them, you have likely not designed it properly.
---
#### Proc-Macros
Note that there are special considerations when documenting proc macros. Doc
links will appear to function _within_ your proc macro crate, but often will no
longer function when these proc macros are re-exported elsewhere in your
project. The exception is doc links to _other proc macros_ which will function
just fine if they are also being re-exported. It is also often necessary to
disambiguate between a proc macro and a function of the same name, which can be
done using the `macro@my_macro_name` syntax in your link. 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).
Note that there are special considerations when documenting proc macros. Doc links will appear to function _within_ your
proc macro crate, but often will no longer function when these proc macros are re-exported elsewhere in your project.
The exception is doc links to _other proc macros_ which will function just fine if they are also being re-exported. It
is also often necessary to disambiguate between a proc macro and a function of the same name, which can be done using
the `macro@my_macro_name` syntax in your link. 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).
---
### Other Guidelines
The above five guidelines must always be reasonably respected in the
documentation.
The above five guidelines must always be reasonably respected in the documentation.
The following are a set of notes that may not necessarily hold in all
circumstances:
The following are a set of notes that may not necessarily hold in all circumstances:
---
#### Document Through Code
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.
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.
> Our north star is self-documenting code that also happens to be well-documented
and littered with examples.
> Our north star is self-documenting code that also happens to be well-documented and littered with examples.
* Your written documents should *complement* the code, not *repeat* it. As an
example, a documentation on top of a code example should never look like the
following:
- Your written documents should *complement* the code, not *repeat* it. As an example, a documentation on top of a code
example should never look like the following:
```rust
/// Sends request and handles the response.
@@ -175,15 +159,14 @@ following:
}
```
In the above example, the documentation has added no useful information not
already contained within the properly-named trait and is redundant.
In the above example, the documentation has added no useful information not already contained within the properly-named
trait and is redundant.
---
#### Formatting Matters
The way you format your documents (newlines, heading and so on) makes a
difference. Consider the below examples:
The way you format your documents (newlines, heading and so on) makes a difference. Consider the below examples:
```rust
/// This function works with input u32 x and multiplies it by two. If
@@ -206,16 +189,15 @@ fn multiply_by_2(x: u32) -> u32 { .. }
// More efficiency can be achieved if we improve this via such and such.
fn multiply_by_2(x: u32) -> u32 { .. }
```
They are both roughly conveying the same set of facts, but one is easier to
follow because it was formatted cleanly. Especially for traits and types that
you can foresee will be seen and used a lot, try and write a well formatted
They are both roughly conveying the same set of facts, but one is easier to follow because it was formatted cleanly.
Especially for traits and types that you can foresee will be seen and used a lot, try and write a well formatted
version.
Similarly, make sure your comments are wrapped at 100 characters line-width (as
defined by our [`rustfmt.toml`](../rustfmt.toml)), no **more and no less**! The
more is fixed by `rustfmt` and our CI, but if you (for some unknown reason)
wrap your lines at 59 characters, it will pass the CI, and it will not look good
🫣. Consider using a plugin like [rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) (for Visual Studio Code) to properly do this.
Similarly, make sure your comments are wrapped at 100 characters line-width (as defined by our
[`rustfmt.toml`](../rustfmt.toml)), no **more and no less**! The more is fixed by `rustfmt` and our CI, but if you (for
some unknown reason) wrap your lines at 59 characters, it will pass the CI, and it will not look good 🫣. Consider using
a plugin like [rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) (for Visual Studio Code) to
properly do this.
[^1]: Those that help two pallets talk to each other.
@@ -224,12 +206,11 @@ wrap your lines at 59 characters, it will pass the CI, and it will not look good
## Pallet Crates
The guidelines so far have been general in nature, and are applicable to crates
that are pallets and crates that're not pallets.
The guidelines so far have been general in nature, and are applicable to crates that are pallets and crates that're not
pallets.
The following is relevant to how to document parts of a crate that is a pallet.
See [`pallet-fast-unstake`](../frame/fast-unstake/src/lib.rs) as one example of
adhering these guidelines.
The following is relevant to how to document parts of a crate that is a pallet. See
[`pallet-fast-unstake`](../frame/fast-unstake/src/lib.rs) as one example of adhering these guidelines.
---
@@ -252,15 +233,20 @@ For the top-level pallet docs, consider the following template:
//!
//! ### Example
//!
//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to reuse these as examples>.
//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to reuse
//! these as examples>.
//!
//! ## Pallet API
//!
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the below line as-is:>
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated.
//! There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways.
//! You can use the below line as-is:>
//!
//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its configuration trait, dispatchables, storage items, events and errors.
//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its configuration
//! trait, dispatchables, storage items, events and errors.
//!
//! <The audience of this is those who want to know how this pallet works, to the extent of being able to build something on top of it, like a DApp or another pallet>
//! <The audience of this is those who want to know how this pallet works, to the extent of being able to build something
//! on top of it, like a DApp or another pallet>
//!
//! This section can most often be left as-is.
//!
@@ -268,7 +254,8 @@ For the top-level pallet docs, consider the following template:
//!
//! <The format of this section is up to you, but we suggest the Design-oriented approach that follows>
//!
//! <The audience of this would be your future self, or anyone who wants to gain a deep understanding of how the pallet works so that they can eventually propose optimizations to it>
//! <The audience of this would be your future self, or anyone who wants to gain a deep understanding of how the pallet
//! works so that they can eventually propose optimizations to it>
//!
//! ### Design Goals (optional)
//!
@@ -276,31 +263,31 @@ For the top-level pallet docs, consider the following template:
//!
//! ### Design (optional)
//!
//! <Describe how you've reached those goals. This should describe the storage layout of your pallet and what was your approach in designing it that way.>
//! <Describe how you've reached those goals. This should describe the storage layout of your pallet and what was your
//! approach in designing it that way.>
//!
//! ### Terminology (optional)
//!
//! <Optionally, explain any non-obvious terminology here. You can link to it if you want to use the terminology further up>
//! <Optionally, explain any non-obvious terminology here. You can link to it if you want to use the terminology further
//! up>
```
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
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`.
Nonetheless, the high level flow of going from the most high level explanation
to the most low level explanation is important to follow.
Nonetheless, the high level flow of going from the most high level explanation to the most low level explanation is
important to follow.
As a rule of thumb, the Heading 2s (`##`) in this template can be considered a
strict rule, while the Heading 3s (`###`) and beyond are flexible.
As a rule of thumb, the Heading 2s (`##`) in this template can be considered a strict rule, while the Heading 3s (`###`)
and beyond are flexible.
---
#### Polkadot and Substrate
Optionally, in order to demonstrate the relation between the two, you can start
the pallet documentation with:
Optionally, in order to demonstrate the relation between the two, you can start the pallet documentation with:
```
//! > Made with *Substrate*, for *Polkadot*.
@@ -331,7 +318,8 @@ For each dispatchable (`fn` item inside `#[pallet::call]`), consider the followi
///
/// ## Errors (optional)
///
/// <If an extensive list of errors can be returned, list them individually instead of mentioning them in the section above>
/// <If an extensive list of errors can be returned, list them individually instead of mentioning them in the section
/// above>
///
/// ## Events (optional)
///
@@ -339,29 +327,26 @@ For each dispatchable (`fn` item inside `#[pallet::call]`), consider the followi
pub fn name_of_dispatchable(origin: OriginFor<T>, ...) -> DispatchResult {}
```
Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by wallets and explorers.
Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by
wallets and explorers.
---
### Storage Items
1. If a map-like type is being used, always note the choice of your hashers as
private code docs (`// Hasher X chosen because ...`). Recall that this is not
relevant information to external people, so it must be documented as `//`.
1. If a map-like type is being used, always note the choice of your hashers as private code docs (`// Hasher X chosen
because ...`). Recall that this is not relevant information to external people, so it must be documented as `//`.
2. Consider explaining the crypto-economics of how a deposit is being taken in
return of the storage being used.
2. Consider explaining the crypto-economics of how a deposit is being taken in return of the storage being used.
3. Consider explaining why it is safe for the storage item to be unbounded, if
`#[pallet::unbounded]` or `#[pallet::without_storage_info]` is being used.
3. Consider explaining why it is safe for the storage item to be unbounded, if `#[pallet::unbounded]` or
`#[pallet::without_storage_info]` is being used.
---
### Errors and Events
Consider the fact that, similar to dispatchables, these docs will be part of
the metadata of the associated event/error, and might be used by wallets and
explorers.
Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error,
and might be used by wallets and explorers.
Specifically for `error`, explain why the error has happened, and what can be
done in order to avoid it.
Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it.
docs/PULL_REQUEST_TEMPLATE.md
+15 -11
View File
@@ -2,25 +2,27 @@
✄ -----------------------------------------------------------------------------
Thank you for your Pull Request! 🙏 Please make sure it follows the contribution
guidelines outlined in [this document](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md) and fill out the
sections below. Once you're ready to submit your PR for review, please delete
this section and leave only the text under the "Description" heading.
Thank you for your Pull Request! 🙏 Please make sure it follows the contribution guidelines outlined in
[this document](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md) and fill
out the sections below. Once you're ready to submit your PR for review, please
delete this section and leave only the text under the "Description" heading.
# Description
*Please include a summary of the changes and the related issue. Please also include relevant motivation and context, including:*
*Please include a summary of the changes and the related issue. Please also include relevant motivation and context,
including:*
- What does this PR do?
- Why are these changes needed?
- How were these changes implemented and what do they affect?
*Use [Github semantic linking](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) to address any open issues this PR relates to or closes.*
*Use [Github semantic
linking](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
to address any open issues this PR relates to or closes.*
Fixes # (issue number, *if applicable*)
Fixes # (issue number, *if applicable*)
Closes # (issue number, *if applicable*)
Closes # (issue number, *if applicable*)
Polkadot companion: (*if applicable*)
@@ -29,10 +31,12 @@ Cumulus companion: (*if applicable*)
# Checklist
- [ ] My PR includes a detailed description as outlined in the "Description" section above
- [ ] My PR follows the [labeling requirements](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md#process) of this project (at minimum one label for `T` required)
- [ ] My PR follows the [labeling requirements](CONTRIBUTING.md#Process) of this project (at minimum one label for `T`
required)
- [ ] I have made corresponding changes to the documentation (if applicable)
- [ ] I have added tests that prove my fix is effective or that my feature works (if applicable)
- [ ] If this PR alters any external APIs or interfaces used by Polkadot, the corresponding Polkadot PR is ready as well as the corresponding Cumulus PR (optional)
- [ ] If this PR alters any external APIs or interfaces used by Polkadot, the corresponding Polkadot PR is ready as well
as the corresponding Cumulus PR (optional)
You can remove the "Checklist" section once all have been checked. Thank you for your contribution!
docs/STYLE_GUIDE.md
+20 -20
View File
@@ -2,19 +2,19 @@
title: Style Guide for Rust in the Polkadot-SDK
---
Where possible these styles are enforced by settings in `rustfmt.toml` so if you run `cargo fmt`
Where possible these styles are enforced by settings in `rustfmt.toml` so if you run `cargo fmt`
then you will adhere to most of these style guidelines automatically.
# Formatting
- Indent using tabs.
- Lines should be longer than 100 characters long only in exceptional circumstances and certainly
- Indent using tabs.
- Lines should be longer than 100 characters long only in exceptional circumstances and certainly
no longer than 120. For this purpose, tabs are considered 4 characters wide.
- Indent levels should be greater than 5 only in exceptional circumstances and certainly no
- Indent levels should be greater than 5 only in exceptional circumstances and certainly no
greater than 8. If they are greater than 5, then consider using `let` or auxiliary functions in
order to strip out complex inline expressions.
- Never have spaces on a line prior to a non-whitespace character
- Follow-on lines are only ever a single indent from the original line.
- Never have spaces on a line prior to a non-whitespace character
- Follow-on lines are only ever a single indent from the original line.
```rust
fn calculation(some_long_variable_a: i8, some_long_variable_b: i8) -> bool {
@@ -25,7 +25,7 @@ fn calculation(some_long_variable_a: i8, some_long_variable_b: i8) -> bool {
}
```
- Indent level should follow open parens/brackets, but should be collapsed to the smallest number
- Indent level should follow open parens/brackets, but should be collapsed to the smallest number
of levels actually used:
```rust
@@ -45,8 +45,8 @@ fn calculate(
}
```
- `where` is indented, and its items are indented one further.
- Argument lists or function invocations that are too long to fit on one line are indented
- `where` is indented, and its items are indented one further.
- Argument lists or function invocations that are too long to fit on one line are indented
similarly to code blocks, and once one param is indented in such a way, all others should be,
too. Run-on parameter lists are also acceptable for single-line run-ons of basic function calls.
@@ -92,7 +92,7 @@ fn foo(really_long_parameter_name_1: SomeLongTypeName, really_long_parameter_nam
}
```
- Always end last item of a multi-line comma-delimited set with `,` when legal:
- Always end last item of a multi-line comma-delimited set with `,` when legal:
```rust
struct Point<T> {
@@ -104,7 +104,7 @@ struct Point<T> {
enum Meal { Breakfast, Lunch, Dinner };
```
- Avoid trailing `;`s where unneeded.
- Avoid trailing `;`s where unneeded.
```rust
if condition {
@@ -112,8 +112,8 @@ if condition {
}
```
- `match` arms may be either blocks or have a trailing `,` but not both.
- Blocks should not be used unnecessarily.
- `match` arms may be either blocks or have a trailing `,` but not both.
- Blocks should not be used unnecessarily.
```rust
match meal {
@@ -126,7 +126,7 @@ match meal {
# Style
- Panickers require explicit proofs they don't trigger. Calling `unwrap` is discouraged. The
- Panickers require explicit proofs they don't trigger. Calling `unwrap` is discouraged. The
exception to this rule is test code. Avoiding panickers by restructuring code is preferred if
feasible.
@@ -139,14 +139,14 @@ let mut target_path =
);
```
- Unsafe code requires explicit proofs just as panickers do. When introducing unsafe code,
- Unsafe code requires explicit proofs just as panickers do. When introducing unsafe code,
consider trade-offs between efficiency on one hand and reliability, maintenance costs, and
security on the other. Here is a list of questions that may help evaluating the trade-off while
preparing or reviewing a PR:
- how much more performant or compact the resulting code will be using unsafe code,
- how likely is it that invariants could be violated,
- are issues stemming from the use of unsafe code caught by existing tests/tooling,
- what are the consequences if the problems slip into production.
- how much more performant or compact the resulting code will be using unsafe code,
- how likely is it that invariants could be violated,
- are issues stemming from the use of unsafe code caught by existing tests/tooling,
- what are the consequences if the problems slip into production.
# Manifest Formatting
@@ -177,4 +177,4 @@ default = [
# Comments go here as well ;)
"std",
]
```
```
docs/markdown_linting.md
+20
View File
@@ -0,0 +1,20 @@
# Markdown linting
Since the introduction of [PR #1309](https://github.com/paritytech/polkadot-sdk/pull/1309), the markdown
files in this repository are checked by a linter for formatting and consistency.
The linter used is [`markdownlint`](https://github.com/DavidAnson/markdownlint) and can be installed locally on your
machine. It can also be setup as [pre-commit hook](https://github.com/igorshubovych/markdownlint-cli#use-with-pre-commit)
to ensure that your markdown is passing all the tests.
The rules in place are defined
[here](https://github.com/paritytech/polkadot-sdk/blob/master/.github/.markdownlint.yaml).
You may run `markdownlint` locally using:
```
markdownlint --config .github/.markdownlint.yaml --ignore target .
```
There are also plugins for your favorite editor, that can ensure that most
of the rules will pass and fix typical issues (such as trailing spaces,
missing eof new line, long lines, etc...)