pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-26 01:47:55 +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
substrate/docs/STYLE_GUIDE.md
+35 -35
View File
@@ -2,19 +2,18 @@
title: Style Guide for Rust in Substrate
---
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.
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.
# Code Formatting
- 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
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.
- 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 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.
```rust
fn calculation(some_long_variable_a: i8, some_long_variable_b: i8) -> bool {
@@ -25,8 +24,8 @@ 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
of levels actually used:
- Indent level should follow open parens/brackets, but should be collapsed to the smallest number of levels actually
used:
```rust
fn calculate(
@@ -45,10 +44,10 @@ 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
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.
- `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.
```rust
// OK
@@ -92,7 +91,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 +103,7 @@ struct Point<T> {
enum Meal { Breakfast, Lunch, Dinner };
```
- Avoid trailing `;`s where unneeded.
- Avoid trailing `;`s where unneeded.
```rust
if condition {
@@ -112,8 +111,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,9 +125,8 @@ match meal {
# Style
- 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.
- 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.
```rust
let mut target_path =
@@ -139,21 +137,22 @@ let mut target_path =
);
```
- 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.
- 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.
# Manifest Formatting
> **TLDR**
> You can use the CLI tool [Zepter](https://crates.io/crates/zepter) to format the files: `zepter format features`
> **TLDR** You can use the CLI tool [Zepter](https://crates.io/crates/zepter) to format the files: `zepter format
> features`
Rust `Cargo.toml` files need to respect certain formatting rules. All entries need to be alphabetically sorted. This makes it easier to read them and insert new entries. The exhaustive list of rules is enforced by the CI. The general format looks like this:
Rust `Cargo.toml` files need to respect certain formatting rules. All entries need to be alphabetically sorted. This
makes it easier to read them and insert new entries. The exhaustive list of rules is enforced by the CI. The general
format looks like this:
- The feature is written as a single line if it fits within 80 chars:
```toml
@@ -161,7 +160,8 @@ Rust `Cargo.toml` files need to respect certain formatting rules. All entries ne
default = [ "std" ]
```
- Otherwise the feature is broken down into multiple lines with one entry per line. Each line is padded with one tab and no trailing spaces but a trailing comma.
- Otherwise the feature is broken down into multiple lines with one entry per line. Each line is padded with one tab and
no trailing spaces but a trailing comma.
```toml
[features]
default = [