Improve the rust style guide doc

- Make the levels of headings consistent in this whole document
- Fix some headings
- Remove redundant empty lines
- Follow the markdown linter advices to use the same symbol for different level of unordered list entries

Author: ShapelessCat

src/doc/style-guide/src/README.md

@@ -100,10 +100,12 @@ fn baz() {}
 ```
 
 ### [Module-level items](items.md)
+
 ### [Statements](statements.md)
+
 ### [Expressions](expressions.md)
-### [Types](types.md)
 
+### [Types](types.md)
 
 ### Comments
 

src/doc/style-guide/src/SUMMARY.md

@@ -2,11 +2,11 @@
 
 [Introduction](README.md)
 
-- [Items](items.md)
-- [Statements](statements.md)
-- [Expressions](expressions.md)
-- [Types and Bounds](types.md)
-- [Other style advice](advice.md)
-- [`Cargo.toml` conventions](cargo.md)
-- [Guiding principles and rationale](principles.md)
-- [Nightly-only syntax](nightly.md)
+* [Items](items.md)
+* [Statements](statements.md)
+* [Expressions](expressions.md)
+* [Types and Bounds](types.md)
+* [Other style advice](advice.md)
+* [`Cargo.toml` conventions](cargo.md)
+* [Guiding principles and rationale](principles.md)
+* [Nightly-only syntax](nightly.md)

src/doc/style-guide/src/advice.md

@@ -18,16 +18,16 @@ if y {
 
 ## Names
 
- * Types shall be `UpperCamelCase`,
- * Enum variants shall be `UpperCamelCase`,
- * Struct fields shall be `snake_case`,
- * Function and method names shall be `snake_case`,
- * Local variables shall be `snake_case`,
- * Macro names shall be `snake_case`,
- * Constants (`const`s and immutable `static`s) shall be `SCREAMING_SNAKE_CASE`.
- * When a name is forbidden because it is a reserved word (such as `crate`),
-   either use a raw identifier (`r#crate`) or use a trailing underscore
-   (`crate_`). Don't misspell the word (`krate`).
+* Types shall be `UpperCamelCase`,
+* Enum variants shall be `UpperCamelCase`,
+* Struct fields shall be `snake_case`,
+* Function and method names shall be `snake_case`,
+* Local variables shall be `snake_case`,
+* Macro names shall be `snake_case`,
+* Constants (`const`s and immutable `static`s) shall be `SCREAMING_SNAKE_CASE`.
+* When a name is forbidden because it is a reserved word (such as `crate`),
+  either use a raw identifier (`r#crate`) or use a trailing underscore
+  (`crate_`). Don't misspell the word (`krate`).
 
 ### Modules
 

src/doc/style-guide/src/expressions.md

@@ -1,6 +1,6 @@
-## Expressions
+# Expressions
 
-### Blocks
+## Blocks
 
 A block expression must have a newline after the initial `{` and before the
 terminal `}`, unless it qualifies to be written as a single line based on
@@ -116,8 +116,7 @@ fn main() {
 }
 ```
 
-
-### Closures
+## Closures
 
 Don't put any extra spaces before the first `|` (unless the closure is prefixed
 by a keyword such as `move`); put a space between the second `|` and the
@@ -155,8 +154,7 @@ move |arg1: i32, arg2: i32| -> i32 {
 }
 ```
 
-
-### Struct literals
+## Struct literals
 
 If a struct literal is *small*, format it on a single line, and do not use a
 trailing comma. If not, split it across multiple lines, with each field on its
@@ -185,8 +183,7 @@ let f = Foo {
 };
 ```
 
-
-### Tuple literals
+## Tuple literals
 
 Use a single-line form where possible. Do not put spaces between the opening
 parenthesis and the first element, or between the last element and the closing
@@ -205,8 +202,7 @@ let x = (
 );
 ```
 
-
-### Tuple struct literals
+## Tuple struct literals
 
 Do not put space between the identifier and the opening parenthesis. Otherwise,
 follow the rules for tuple literals:
@@ -220,8 +216,7 @@ let x = Foo(
 );
 ```
 
-
-### Enum literals
+## Enum literals
 
 Follow the formatting rules for the various struct literals. Prefer using the
 name of the enum as a qualifying name, unless the enum is in the prelude:
@@ -235,8 +230,7 @@ Foo::Baz {
 Ok(an_expr)
 ```
 
-
-### Array literals
+## Array literals
 
 Write small array literals on a single line. Do not put spaces between the opening
 square bracket and the first element, or between the last element and the closing
@@ -276,8 +270,7 @@ fn main() {
 }
 ```
 
-
-### Array accesses, indexing, and slicing.
+## Array accesses, indexing, and slicing
 
 Don't put spaces around the square brackets. Avoid breaking lines if possible.
 Never break a line between the target expression and the opening square
@@ -300,13 +293,13 @@ fn main() {
 }
 ```
 
-### Unary operations
+## Unary operations
 
 Do not include a space between a unary op and its operand (i.e., `!x`, not
 `! x`). However, there must be a space after `&mut`. Avoid line-breaking
 between a unary operator and its operand.
 
-### Binary operations
+## Binary operations
 
 Do include spaces around binary ops (i.e., `x + 1`, not `x+1`) (including `=`
 and other assignment operators such as `+=` or `*=`).
@@ -335,7 +328,7 @@ foo_bar
 Prefer line-breaking at an assignment operator (either `=` or `+=`, etc.) rather
 than at other binary operators.
 
-### Control flow
+## Control flow
 
 Do not include extraneous parentheses for `if` and `while` expressions.
 
@@ -354,7 +347,7 @@ if (true) {
 Do include extraneous parentheses if it makes an arithmetic or logic expression
 easier to understand (`(x * 15) + (y * 20)` is fine)
 
-### Function calls
+## Function calls
 
 Do not put a space between the function name, and the opening parenthesis.
 
@@ -364,7 +357,7 @@ Do put a space between an argument, and the comma which precedes it.
 
 Prefer not to break a line in the callee expression.
 
-#### Single-line calls
+### Single-line calls
 
 Do not put a space between the function name and open paren, between the open
 paren and the first argument, or between the last argument and the close paren.
@@ -375,7 +368,7 @@ Do not put a comma after the last argument.
 foo(x, y, z)
 ```
 
-#### Multi-line calls
+### Multi-line calls
 
 If the function call is not *small*, it would otherwise over-run the max width,
 or any argument or the callee is multi-line, then format the call across
@@ -390,8 +383,7 @@ a_function_call(
 )
 ```
 
-
-### Method calls
+## Method calls
 
 Follow the function rules for calling.
 
@@ -401,15 +393,14 @@ Do not put any spaces around the `.`.
 x.foo().bar().baz(x, y, z);
 ```
 
-
-### Macro uses
+## Macro uses
 
 If a macro can be parsed like other constructs, format it like those
 constructs. For example, a macro use `foo!(a, b, c)` can be parsed like a
 function call (ignoring the `!`), so format it using the rules for function
 calls.
 
-#### Special case macros
+### Special case macros
 
 For macros which take a format string, if all other arguments are *small*,
 format the arguments before the format string on a single line if they fit, and
@@ -430,17 +421,15 @@ assert_eq!(
 );
 ```
 
-
-### Casts (`as`)
+## Casts (`as`)
 
 Put spaces before and after `as`:
 
 ```rust
 let cstr = "Hi\0" as *const str as *const [u8] as *const std::os::raw::c_char;
 ```
 
-
-### Chains of fields and method calls
+## Chains of fields and method calls
 
 A chain is a sequence of field accesses, method calls, and/or uses of the try
 operator `?`. E.g., `a.b.c().d` or `foo?.bar().baz?`.
@@ -478,7 +467,7 @@ foo(
     .qux();
 ```
 
-#### Multi-line elements
+### Multi-line elements
 
 If any element in a chain is formatted across multiple lines, put that element
 and any later elements on their own lines.
@@ -513,7 +502,7 @@ self.pre_comment.as_ref().map_or(
 )
 ```
 
-### Control flow expressions
+## Control flow expressions
 
 This section covers `if`, `if let`, `loop`, `while`, `while let`, and `for`
 expressions.
@@ -584,8 +573,7 @@ if !self.config.file_lines().intersects(
 }
 ```
 
-
-#### Single line `if else`
+### Single line `if else`
 
 Put an `if else` or `if let else` on a single line if it occurs in expression
 context (i.e., is not a standalone statement), it contains a single `else`
@@ -608,8 +596,7 @@ if x {
 }
 ```
 
-
-### Match
+## Match
 
 Prefer not to line-break inside the discriminant expression. Always break after
 the opening brace and before the closing brace. Block-indent the match arms
@@ -718,7 +705,7 @@ match foo {
 }
 ```
 
-#### Line-breaking
+### Line-breaking
 
 If using a block form on the right-hand side of a match arm makes it possible
 to avoid breaking on the left-hand side, do that:
@@ -812,8 +799,7 @@ small_no_tuple:
 
 E.g., `&&Some(foo)` matches, `Foo(4, Bar)` does not.
 
-
-### Combinable expressions
+## Combinable expressions
 
 Where a function call has a single argument, and that argument is formatted
 across multiple-lines, format the outer call as if it were a single-line call,
@@ -861,8 +847,7 @@ foo(first_arg, x, |param| {
 })
 ```
 
-
-### Ranges
+## Ranges
 
 Do not put spaces in ranges, e.g., `0..10`, `x..=y`, `..x.len()`, `foo..`.
 
@@ -879,8 +864,7 @@ For the sake of indicating precedence, if either bound is a compound
 expression, use parentheses around it, e.g., `..(x + 1)`, `(x.f)..(x.f.len())`,
 or `0..(x - 10)`.
 
-
-### Hexadecimal literals
+## Hexadecimal literals
 
 Hexadecimal literals may use upper- or lower-case letters, but they must not be
 mixed within the same literal. Projects should use the same case for all