Merging upstream version 1.73.0+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

10 files changed, 440 insertions, 421 deletions

diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md
index b8aa64ba1..f4d759673 100644
--- a/src/doc/style-guide/src/README.md
+++ b/src/doc/style-guide/src/README.md
@@ -36,11 +36,10 @@ options.
 
 ### Indentation and line width
 
-* Use spaces, not tabs.
-* Each level of indentation must be four spaces (that is, all indentation
-  outside of string literals and comments must be a multiple of four).
-* The maximum width for a line is 100 characters.
-* A tool may choose to make some of these configurable.
+- Use spaces, not tabs.
+- Each level of indentation must be 4 spaces (that is, all indentation
+  outside of string literals and comments must be a multiple of 4).
+- The maximum width for a line is 100 characters.
 
 #### Block indent
 
@@ -63,7 +62,8 @@ example) and less rightward drift.
 
 ### Trailing commas
 
-Lists should have a trailing comma when followed by a newline:
+In comma-separated lists of any kind, use a trailing comma when followed by a
+newline:
 
 ```rust
 function_call(
@@ -99,13 +99,13 @@ fn bar() {}
 fn baz() {}
 ```
 
-Formatting tools may wish to make the bounds on blank lines configurable.
-
 ### [Module-level items](items.md)
+
 ### [Statements](statements.md)
+
 ### [Expressions](expressions.md)
-### [Types](types.md)
 
+### [Types](types.md)
 
 ### Comments
 
@@ -114,17 +114,17 @@ formatter might skip formatting of comments.
 
 Prefer line comments (`//`) to block comments (`/* ... */`).
 
-When using line comments there should be a single space after the opening sigil.
+When using line comments, put a single space after the opening sigil.
 
-When using single-line block comments there should be a single space after the
-opening sigil and before the closing sigil. Multi-line block comments should
-have a newline after the opening sigil and before the closing sigil.
+When using single-line block comments, put a single space after the opening
+sigil and before the closing sigil. For multi-line block comments, put a
+newline after the opening sigil, and a newline before the closing sigil.
 
-Prefer to put a comment on its own line. Where a comment follows code, there
-should be a single space before it. Where a block comment is inline, there
-should be surrounding whitespace as if it were an identifier or keyword. There
-should be no trailing whitespace after a comment or at the end of any line in a
-multi-line comment. Examples:
+Prefer to put a comment on its own line. Where a comment follows code, put a
+single space before it. Where a block comment appears inline, use surrounding
+whitespace as if it were an identifier or keyword. Do not include trailing
+whitespace after a comment or at the end of any line in a multi-line comment.
+Examples:
 
 ```rust
 // A comment on an item.
@@ -173,7 +173,7 @@ Prefer line comments (`///`) to block comments (`/** ... */`).
 Prefer outer doc comments (`///` or `/** ... */`), only use inner doc comments
 (`//!` and `/*! ... */`) to write module-level or crate-level documentation.
 
-Doc comments should come before attributes.
+Put doc comments before attributes.
 
 ### Attributes
 
@@ -198,18 +198,20 @@ struct CRepr {
 }
 ```
 
-For attributes with an equal sign, there should be a single space before and
-after the `=`, e.g., `#[foo = 42]`.
+For attributes with an equal sign, put a single space before and after the `=`,
+e.g., `#[foo = 42]`.
 
 There must only be a single `derive` attribute. Note for tool authors: if
 combining multiple `derive` attributes into a single attribute, the ordering of
-the derived names should be preserved. E.g., `#[derive(bar)] #[derive(foo)]
-struct Baz;` should be formatted to `#[derive(bar, foo)] struct Baz;`.
+the derived names must generally be preserved for correctness:
+`#[derive(Foo)] #[derive(Bar)] struct Baz;` must be formatted to
+`#[derive(Foo, Bar)] struct Baz;`.
 
 ### *small* items
 
-In many places in this guide we specify that a formatter may format an item
-differently if it is *small*, for example struct literals:
+In many places in this guide we specify formatting that depends on a code
+construct being *small*. For example, single-line vs multi-line struct
+literals:
 
 ```rust
 // Normal formatting
@@ -218,7 +220,7 @@ Foo {
     f2: another_expression(),
 }
 
-// *small* formatting
+// "small" formatting
 Foo { f1, f2 }
 ```
 
@@ -231,10 +233,6 @@ complexity of an item (for example, that all components must be simple names,
 not more complex sub-expressions). For more discussion on suitable heuristics,
 see [this issue](https://github.com/rust-lang-nursery/fmt-rfcs/issues/47).
 
-Tools should give the user an option to ignore such heuristics and always use
-the normal formatting.
-
-
 ## [Non-formatting conventions](advice.md)
 
 ## [Cargo.toml conventions](cargo.md)
diff --git a/src/doc/style-guide/src/SUMMARY.md b/src/doc/style-guide/src/SUMMARY.md
index 606485bfb..64540c399 100644
--- a/src/doc/style-guide/src/SUMMARY.md
+++ b/src/doc/style-guide/src/SUMMARY.md
@@ -9,4 +9,5 @@
 - [Other style advice](advice.md)
 - [`Cargo.toml` conventions](cargo.md)
 - [Guiding principles and rationale](principles.md)
+- [Rust style editions](editions.md)
 - [Nightly-only syntax](nightly.md)
diff --git a/src/doc/style-guide/src/advice.md b/src/doc/style-guide/src/advice.md
index 9a617be50..65cf8cb6e 100644
--- a/src/doc/style-guide/src/advice.md
+++ b/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
 
diff --git a/src/doc/style-guide/src/editions.md b/src/doc/style-guide/src/editions.md
new file mode 100644
index 000000000..5c67a185b
--- /dev/null
+++ b/src/doc/style-guide/src/editions.md
@@ -0,0 +1,46 @@
+# Rust style editions
+
+The default Rust style evolves over time, as Rust does. However, to avoid
+breaking established code style, and CI jobs checking code style, changes to
+the default Rust style only appear in *style editions*.
+
+Code written in a given
+[Rust edition](https://doc.rust-lang.org/edition-guide/)
+uses the corresponding Rust style edition by default. To make it easier to
+migrate code style separately from the semantic changes between Rust editions,
+formatting tools such as `rustfmt` allow updating the style edition separately
+from the Rust edition.
+
+The current version of the style guide describes the latest Rust style edition.
+Each distinct past style will have a corresponding archived version of the
+style guide.
+
+Note that archived versions of the style guide do not document formatting for
+newer Rust constructs that did not exist at the time that version of the style
+guide was archived. However, each style edition will still format all
+constructs valid in that Rust edition, with the style of newer constructs
+coming from the first subsequent style edition providing formatting rules for
+that construct (without any of the systematic/global changes from that style
+edition).
+
+Not all Rust editions have corresponding changes to the Rust style. For
+instance, Rust 2015, Rust 2018, and Rust 2021 all use the same style edition.
+
+## Rust 2024 style edition
+
+This style guide describes the Rust 2024 style edition. The Rust 2024 style
+edition is currently nightly-only and may change before the release of Rust
+2024.
+
+For a full history of changes in the Rust 2024 style edition, see the git
+history of the style guide. Notable changes in the Rust 2024 style edition
+include:
+
+- Miscellaneous `rustfmt` bugfixes.
+
+## Rust 2015/2018/2021 style edition
+
+The archived version of the style guide at
+<https://github.com/rust-lang/rust/tree/37343f4a4d4ed7ad0891cb79e8eb25acf43fb821/src/doc/style-guide/src>
+describes the style edition corresponding to Rust 2015, Rust 2018, and Rust
+2021.
diff --git a/src/doc/style-guide/src/expressions.md b/src/doc/style-guide/src/expressions.md
index 143161da6..32c604f9f 100644
--- a/src/doc/style-guide/src/expressions.md
+++ b/src/doc/style-guide/src/expressions.md
@@ -1,11 +1,14 @@
-## Expressions
+# Expressions
 
-### Blocks
+## Blocks
 
-A block expression should have a newline after the initial `{` and before the
-terminal `}`. Any qualifier before the block (e.g., `unsafe`) should always be
-on the same line as the opening brace, and separated with a single space. The
-contents of the block should be block indented:
+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
+another style rule.
+
+A keyword before the block (such as `unsafe` or `async`) must be on the same
+line as the opening brace, with a single space between the keyword and the
+opening brace. Indent the contents of the block.
 
 ```rust
 fn block_as_stmt() {
@@ -40,7 +43,7 @@ fn unsafe_block_as_stmt() {
 }
 ```
 
-If a block has an attribute, it should be on its own line:
+If a block has an attribute, put it on its own line before the block:
 
 ```rust
 fn block_as_stmt() {
@@ -54,18 +57,18 @@ fn block_as_stmt() {
 }
 ```
 
-Avoid writing comments on the same line as the braces.
+Avoid writing comments on the same lines as either of the braces.
 
-An empty block should be written as `{}`.
+Write an empty block as `{}`.
 
-A block may be written on a single line if:
+Write a block on a single line if:
 
-* it is either used in expression position (not statement position) or is an
-  unsafe block in statement position
-* contains a single-line expression and no statements
-* contains no comments
+- it is either used in expression position (not statement position) or is an
+  unsafe block in statement position,
+- it contains a single-line expression and no statements, and
+- it contains no comments
 
-A single line block should have spaces after the opening brace and before the
+For a single-line block, put spaces after the opening brace and before the
 closing brace.
 
 Examples:
@@ -113,18 +116,17 @@ fn main() {
 }
 ```
 
-
-### Closures
+## Closures
 
 Don't put any extra spaces before the first `|` (unless the closure is prefixed
-by `move`); put a space between the second `|` and the expression of the
-closure. Between the `|`s, you should use function definition syntax, however,
-elide types where possible.
+by a keyword such as `move`); put a space between the second `|` and the
+expression of the closure. Between the `|`s, use function definition syntax,
+but elide types where possible.
 
 Use closures without the enclosing `{}`, if possible. Add the `{}` when you have
-a return type, when there are statements, there are comments in the body, or the
-body expression spans multiple lines and is a control-flow expression. If using
-braces, follow the rules above for blocks. Examples:
+a return type, when there are statements, when there are comments inside the
+closure, or when the body expression is a control-flow expression that spans
+multiple lines. If using braces, follow the rules above for blocks. Examples:
 
 ```rust
 |arg1, arg2| expr
@@ -152,16 +154,16 @@ 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
+own block-indented line, and use a trailing comma.
 
-If a struct literal is *small* it may be formatted on a single line. If not,
-each field should be on it's own, block-indented line. There should be a
-trailing comma in the multi-line form only. There should be a space after the
-colon only.
+For each `field: value` entry, put a space after the colon only.
 
-There should be a space before the opening brace. In the single-line form there
-should be spaces after the opening brace and before the closing brace.
+Put a space before the opening brace. In the single-line form, put spaces after
+the opening brace and before the closing brace.
 
 ```rust
 Foo { field1, field2: 0 }
@@ -172,19 +174,24 @@ let f = Foo {
 ```
 
 Functional record update syntax is treated like a field, but it must never have
-a trailing comma. There should be no space after `..`.
+a trailing comma. Do not put a space after `..`.
 
+```rust
 let f = Foo {
     field1,
     ..an_expr
 };
+```
 
+## 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
+parenthesis. Separate elements with a comma followed by a space.
 
-Use a single-line form where possible. There should not be spaces around the
-parentheses. Where a single-line form is not possible, each element of the tuple
-should be on its own block-indented line and there should be a trailing comma.
+Where a single-line form is not possible, write the tuple across
+multiple lines, with each element of the tuple on its own block-indented line,
+and use a trailing comma.
 
 ```rust
 (a, b, c)
@@ -195,17 +202,24 @@ 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:
 
-There should be no space between the identifier and the opening parenthesis.
-Otherwise, follow the rules for tuple literals, e.g., `Foo(a, b)`.
+```rust
+Foo(a, b, c)
 
+let x = Foo(
+    a_long_expr,
+    another_very_long_expr,
+);
+```
 
-### 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. E.g.,
+name of the enum as a qualifying name, unless the enum is in the prelude:
 
 ```rust
 Foo::Bar(a, b)
@@ -216,27 +230,31 @@ 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
+square bracket. Separate elements with a comma followed by a space.
 
-For simple array literals, avoid line breaking, no spaces around square
-brackets, contents of the array should be separated by commas and spaces. If
-using the repeating initialiser, there should be a space after the semicolon
-only. Apply the same rules if using the `vec!` or similar macros (always use
-square brackets here). Examples:
+If using the repeating initializer, put a space after the semicolon
+only.
+
+Apply the same rules if using `vec!` or similar array-like macros; always use
+square brackets with such macros. Examples:
 
 ```rust
 fn main() {
-    [1, 2, 3];
-    vec![a, b, c, d];
+    let x = [1, 2, 3];
+    let y = vec![a, b, c, d];
     let a = [42; 10];
 }
 ```
 
-If a line must be broken, prefer breaking only after the `;`, if possible.
-Otherwise, follow the rules below for function calls. In any case, the contents
-of the initialiser should be block indented and there should be line breaks
-after the opening bracket and before the closing bracket:
+For arrays that have to be broken across lines, if using the repeating
+initializer, break after the `;`, not before. Otherwise, follow the rules below
+for function calls. In any case, block-indent the contents of the initializer,
+and put line breaks after the opening square bracket and before the closing
+square bracket:
 
 ```rust
 fn main() {
@@ -252,14 +270,14 @@ fn main() {
 }
 ```
 
+## Array accesses, indexing, and slicing
 
-### Array accesses, indexing, and slicing.
-
-No spaces around the square brackets, avoid breaking lines if possible, never
-break a line between the target expression and the opening bracket. If the
-indexing expression covers multiple lines, then it should be block indented and
-there should be newlines after the opening brackets and before the closing
-bracket. However, this should be avoided where possible.
+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
+bracket. If the indexing expression must be broken onto a subsequent line, or
+spans multiple lines itself, then block-indent the indexing expression, and put
+newlines after the opening square bracket and before the closing square
+bracket:
 
 Examples:
 
@@ -275,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 `*=`).
@@ -291,7 +309,7 @@ if you have `t: &T`, and `u: U`, prefer `*t op u` to `t op &u`. In general,
 within expressions, prefer dereferencing to taking references, unless necessary
 (e.g. to avoid an unnecessarily expensive operation).
 
-Use parentheses liberally, do not necessarily elide them due to precedence.
+Use parentheses liberally; do not necessarily elide them due to precedence.
 Tools should not automatically insert or remove parentheses. Do not use spaces
 to indicate precedence.
 
@@ -310,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.
 
@@ -329,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.
 
@@ -339,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.
@@ -350,13 +368,13 @@ 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 the call should be formatted
-across multiple lines. In this case, each argument should be on it's own block-
-indented line, there should be a newline after the opening parenthesis and
-before the closing parenthesis, and there should be a trailing comma. E.g.,
+or any argument or the callee is multi-line, then format the call across
+multiple lines. In this case, put each argument on its own block-indented line,
+break after the opening parenthesis and before the closing parenthesis,
+and use a trailing comma:
 
 ```rust
 a_function_call(
@@ -365,8 +383,7 @@ a_function_call(
 )
 ```
 
-
-### Method calls
+## Method calls
 
 Follow the function rules for calling.
 
@@ -376,20 +393,20 @@ Do not put any spaces around the `.`.
 x.foo().bar().baz(x, y, z);
 ```
 
+## Macro uses
 
-### Macro uses
-
-Macros which can be parsed like other constructs should be formatted like those
+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 `!`), therefore it should be formatted following the
-rules for function calls.
+function call (ignoring the `!`), so format it using the rules for function
+calls.
 
-#### Special case macros
+### Special case macros
 
-Macros which take a format string and where all other arguments are *small* may
-be formatted with arguments before and after the format string on a single line
-and the format string on its own line, rather than putting each argument on its
-own line. For example,
+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
+format the arguments after the format string on a single line if they fit, with
+the format string on its own line. If the arguments are not small or do not
+fit, put each on its own line as with a function. For example:
 
 ```rust
 println!(
@@ -404,8 +421,7 @@ assert_eq!(
 );
 ```
 
-
-### Casts (`as`)
+## Casts (`as`)
 
 Put spaces before and after `as`:
 
@@ -413,16 +429,15 @@ Put spaces before and after `as`:
 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 and/or method calls. A chain may also
-include the try operator ('?'). E.g., `a.b.c().d` or `foo?.bar().baz?`.
+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?`.
 
-Prefer formatting on one line if possible, and the chain is *small*. If
-formatting on multiple lines, each field access or method call in the chain
-should be on its own line with the line-break before the `.` and after any `?`.
-Each line should be block-indented. E.g.,
+Format the chain on one line if it is "small" and otherwise possible to do so.
+If formatting on multiple lines, put each field access or method call in the
+chain on its own line, with the line-break before the `.` and after any `?`.
+Block-indent each subsequent line:
 
 ```rust
 let foo = bar
@@ -431,13 +446,16 @@ let foo = bar
 ```
 
 If the length of the last line of the first element plus its indentation is
-less than or equal to the indentation of the second line (and there is space),
-then combine the first and second lines, e.g.,
+less than or equal to the indentation of the second line, then combine the
+first and second lines if they fit. Apply this rule recursively.
 
 ```rust
 x.baz?
     .qux()
 
+x.y.z
+    .qux()
+
 let foo = x
     .baz?
     .qux();
@@ -449,14 +467,13 @@ foo(
     .qux();
 ```
 
-#### Multi-line elements
+### Multi-line elements
 
-If any element in a chain is formatted across multiple lines, then that element
-and any later elements must be on their own line. Earlier elements may be kept
-on a single line. E.g.,
+If any element in a chain is formatted across multiple lines, put that element
+and any later elements on their own lines.
 
 ```rust
-a.b.c()?.d
+a.b.c()?
     .foo(
         an_expr,
         another_expr,
@@ -485,18 +502,18 @@ 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.
 
-The keyword, any initial clauses, and the opening brace of the block should be
-on a single line. The usual rules for [block formatting](#blocks) should be
-applied to the block.
+Put the keyword, any initial clauses, and the opening brace of the block all on
+a single line, if they fit. Apply the usual rules for [block
+formatting](#blocks) to the block.
 
-If there is an `else` component, then the closing brace, `else`, any following
-clause, and the opening brace should all be on the same line. There should be a
-single space before and after the `else` keyword. For example:
+If there is an `else` component, then put the closing brace, `else`, any
+following clause, and the opening brace all on the same line, with a single
+space before and after the `else` keyword:
 
 ```rust
 if ... {
@@ -514,10 +531,10 @@ if let ... {
 }
 ```
 
-If the control line needs to be broken, then prefer to break before the `=` in
-`* let` expressions and before `in` in a `for` expression; the following line
-should be block indented. If the control line is broken for any reason, then the
-opening brace should be on its own line and not indented. Examples:
+If the control line needs to be broken, prefer to break before the `=` in `*
+let` expressions and before `in` in a `for` expression; block-indent the
+following line. If the control line is broken for any reason, put the opening
+brace on its own line, not indented. Examples:
 
 ```rust
 while let Some(foo)
@@ -540,10 +557,10 @@ if a_long_expression
 }
 ```
 
-Where the initial clause is multi-lined and ends with one or more closing
-parentheses, square brackets, or braces, and there is nothing else on that line,
-and that line is not indented beyond the indent on the first line of the control
-flow expression, then the opening brace of the block should be put on the same
+Where the initial clause spans multiple lines and ends with one or more closing
+parentheses, square brackets, or braces, and there is nothing else on that
+line, and that line is not indented beyond the indent on the first line of the
+control flow expression, then put the opening brace of the block on the same
 line with a preceding space. For example:
 
 ```rust
@@ -556,12 +573,11 @@ if !self.config.file_lines().intersects(
 }
 ```
 
+### Single line `if else`
 
-#### Single line `if else`
-
-Formatters may place 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` clause, and is *small*. For example:
+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`
+clause, and is *small*:
 
 ```rust
 let y = if x { 0 } else { 1 };
@@ -580,12 +596,11 @@ if x {
 }
 ```
 
+## Match
 
-### Match
-
-Prefer not to line-break inside the discriminant expression. There must always
-be a line break after the opening brace and before the closing brace. The match
-arms must be block indented once:
+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
+once:
 
 ```rust
 match foo {
@@ -599,7 +614,7 @@ let x = match foo.bar.baz() {
 
 Use a trailing comma for a match arm if and only if not using a block.
 
-Never start a match arm pattern with `|`, e.g.,
+Never start a match arm pattern with `|`:
 
 ```rust
 match foo {
@@ -609,14 +624,13 @@ match foo {
     | a_very_long_pattern
     | another_pattern
     | yet_another_pattern
-    | a_forth_pattern => {
+    | a_fourth_pattern => {
         ...
     }
 }
 ```
 
-Prefer
-
+Prefer:
 
 ```rust
 match foo {
@@ -624,7 +638,7 @@ match foo {
     a_very_long_pattern
     | another_pattern
     | yet_another_pattern
-    | a_forth_pattern => {
+    | a_fourth_pattern => {
         ...
     }
 }
@@ -634,11 +648,12 @@ Avoid splitting the left-hand side (before the `=>`) of a match arm where
 possible. If the right-hand side of the match arm is kept on the same line,
 never use a block (unless the block is empty).
 
-If the right-hand side consists of multiple statements or has line comments or
-the start of the line cannot be fit on the same line as the left-hand side, use
-a block.
+If the right-hand side consists of multiple statements, or has line comments,
+or the start of the line does not fit on the same line as the left-hand side,
+use a block. Do not flatten a right-hand side block containing a single macro call
+because its expanded form could contain a trailing semicolon.
 
-The body of a block arm should be block indented once.
+Block-indent the body of a block arm.
 
 Examples:
 
@@ -659,12 +674,16 @@ match foo {
     bar => {}
     // Trailing comma on last item.
     foo => bar,
+    baz => qux!(),
+    lorem => {
+        ipsum!()
+    }
 }
 ```
 
 If the body is a single expression with no line comments and not a control flow
-expression, then it may be started on the same line as the right-hand side. If
-not, then it must be in a block. Example,
+expression, start it on the same line as the left-hand side. If not, then it
+must be in a block. Example:
 
 ```rust
 match foo {
@@ -686,10 +705,10 @@ match foo {
 }
 ```
 
-#### Line-breaking
+### Line-breaking
 
-Where it is possible to use a block form on the right-hand side and avoid
-breaking the left-hand side, do that. E.g.
+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:
 
 ```rust
     // Assuming the following line does not fit in the max width
@@ -721,7 +740,7 @@ body on a new line:
 
 If required to break the pattern, put each clause of the pattern on its own
 line with no additional indent, breaking before the `|`. If there is an `if`
-clause, then you must use the above form:
+clause, use the above form:
 
 ```rust
     a_very_long_pattern
@@ -741,7 +760,7 @@ clause, then you must use the above form:
 ```
 
 If the pattern is multi-line, and the last line is less wide than the indent, do
-not put the `if` clause on a newline. E.g.,
+not put the `if` clause on a new line. E.g.,
 
 ```rust
     Token::Dimension {
@@ -754,8 +773,8 @@ not put the `if` clause on a newline. E.g.,
 ```
 
 If every clause in a pattern is *small*, but the whole pattern does not fit on
-one line, then the pattern may be formatted across multiple lines with as many
-clauses per line as possible. Again break before a `|`:
+one line, then format the pattern across multiple lines with as many clauses
+per line as possible. Again, break before a `|`:
 
 ```rust
     foo | bar | baz
@@ -780,12 +799,11 @@ 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, the outer call may be formatted as if it were a single-
-line call. The same combining behaviour may be applied to any similar
+across multiple-lines, format the outer call as if it were a single-line call,
+if the result fits. Apply the same combining behaviour to any similar
 expressions which have multi-line, block-indented lists of sub-expressions
 delimited by parentheses (e.g., macros or tuple struct literals). E.g.,
 
@@ -803,15 +821,24 @@ foo(|param| {
     action();
     foo(param)
 })
+
+let x = combinable([
+    an_expr,
+    another_expr,
+]);
+
+let arr = [combinable(
+    an_expr,
+    another_expr,
+)];
 ```
 
-Such behaviour should extend recursively, however, tools may choose to limit the
-depth of nesting.
+Apply this behavior recursively.
 
-Only where the multi-line sub-expression is a closure with an explicit block,
-this combining behaviour may be used where there are other arguments, as long as
-all the arguments and the first line of the closure fit on the first line, the
-closure is the last argument, and there is only one closure argument:
+For a function with multiple arguments, if the last argument is a multi-line
+closure with an explicit block, there are no other closure arguments, and all
+the arguments and the first line of the closure fit on the first line, use the
+same combining behavior:
 
 ```rust
 foo(first_arg, x, |param| {
@@ -820,34 +847,30 @@ foo(first_arg, x, |param| {
 })
 ```
 
-
-### Ranges
+## Ranges
 
 Do not put spaces in ranges, e.g., `0..10`, `x..=y`, `..x.len()`, `foo..`.
 
 When writing a range with both upper and lower bounds, if the line must be
-broken, break before the range operator and block indent the second line:
+broken within the range, break before the range operator and block indent the
+second line:
 
 ```rust
 a_long_expression
     ..another_long_expression
 ```
 
-For the sake of indicating precedence, we recommend that if either bound is a
-compound expression, then use parentheses around it, e.g., `..(x + 1)`,
-`(x.f)..(x.f.len())`, or `0..(x - 10)`.
+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
 literals, but we do not make a recommendation for either lower- or upper-case.
-Tools should have an option to convert mixed case literals to upper-case, and
-may have an option to convert all literals to either lower- or upper-case.
-
 
 ## Patterns
 
-Patterns should be formatted like their corresponding expressions. See the
-section on `match` for additional formatting for patterns in match arms.
+Format patterns like their corresponding expressions. See the section on
+`match` for additional formatting for patterns in match arms.
diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md
index 1e0e60248..a6d941f6d 100644
--- a/src/doc/style-guide/src/items.md
+++ b/src/doc/style-guide/src/items.md
@@ -1,4 +1,4 @@
-## Items
+# Items
 
 Items consist of the set of things permitted at the top level of a module.
 However, Rust also allows some items to appear within some other types of
@@ -9,19 +9,17 @@ an item appears at module level or within another item.
 alphabetically.
 
 `use` statements, and module *declarations* (`mod foo;`, not `mod { ... }`)
-must come before other items. We recommend that imports come before module
-declarations; if imports and modules are separated, then they should be ordered
-alphabetically. When sorting, `self` and `super` must come before any other
-names. Module declarations should not be moved if they are annotated with
-`#[macro_use]`, since that may be semantics changing.
+must come before other items. Put imports before module declarations. Sort each
+alphabetically, except that `self` and `super` must come before any other
+names.
 
-Tools should make the above ordering optional.
+Don't automatically move module declarations annotated with `#[macro_use]`,
+since that might change semantics.
 
-
-### Function definitions
+## Function definitions
 
 In Rust, people often find functions by searching for `fn [function-name]`, so
-the formatting of function definitions shold enable this.
+the formatting of function definitions must enable this.
 
 The proper ordering and spacing is:
 
@@ -48,14 +46,13 @@ fn foo(
 
 Note the trailing comma on the last argument.
 
-
-### Tuples and tuple structs
+## Tuples and tuple structs
 
 Write the type list as you would a parameter list to a function.
 
 Build a tuple or tuple struct as you would call a function.
 
-#### Single-line
+### Single-line
 
 ```rust
 struct Bar(Type1, Type2);
@@ -64,7 +61,7 @@ let x = Bar(11, 22);
 let y = (11, 22, 33);
 ```
 
-### Enums
+## Enums
 
 In the declaration, put each variant on its own line, block indented.
 
@@ -83,9 +80,9 @@ enum FooBar {
 }
 ```
 
-If a struct variant is [*small*](index.html#small-items), it may be formatted on
-one line. In this case, do not use a trailing comma for the field list, but do
-put spaces around each brace:
+If a struct variant is [*small*](index.html#small-items), format it on one
+line. In this case, do not use a trailing comma for the field list, but do put
+spaces around each brace:
 
 ```rust
 enum FooBar {
@@ -94,12 +91,11 @@ enum FooBar {
 ```
 
 In an enum with multiple struct variants, if any struct variant is written on
-multiple lines, then the multi-line formatting should be used for all struct
-variants. However, such a situation might be an indication that you should
-factor out the fields of the variant into their own struct.
-
+multiple lines, use the multi-line formatting for all struct variants. However,
+such a situation might be an indication that you should factor out the fields
+of the variant into their own struct.
 
-### Structs and Unions
+## Structs and Unions
 
 Struct names follow on the same line as the `struct` keyword, with the opening
 brace on the same line when it fits within the right margin. All struct fields
@@ -140,12 +136,11 @@ union Foo {
 }
 ```
 
+## Tuple structs
 
-### Tuple structs
-
-Put the whole struct on one line if possible. Types in the parentheses should be
-separated by a comma and space with no trailing comma. No spaces around the
-parentheses or semicolon:
+Put the whole struct on one line if possible. Separate types within the
+parentheses using a comma and space. Don't use a trailing comma for a
+single-line tuple struct. Don't put spaces around the parentheses or semicolon:
 
 ```rust
 pub struct Foo(String, u8);
@@ -154,9 +149,11 @@ pub struct Foo(String, u8);
 Prefer unit structs to empty tuple structs (these only exist to simplify code
 generation), e.g., `struct Foo;` rather than `struct Foo();`.
 
-For more than a few fields, prefer a proper struct with named fields. Given
-this, a tuple struct should always fit on one line. If it does not, block format
-the fields with a field on each line and a trailing comma:
+For more than a few fields (in particular if the tuple struct does not fit on
+one line), prefer a proper struct with named fields.
+
+For a multi-line tuple struct, block-format the fields with a field on each
+line and a trailing comma:
 
 ```rust
 pub struct Foo(
@@ -165,12 +162,11 @@ pub struct Foo(
 );
 ```
 
+## Traits
 
-### Traits
-
-Trait items should be block-indented. If there are no items, the trait may be
-formatted on a single line. Otherwise there should be line-breaks after the
-opening brace and before the closing brace:
+Use block-indent for trait items. If there are no items, format the trait (including its `{}`)
+on a single line. Otherwise, break after the opening brace and before
+the closing brace:
 
 ```rust
 trait Foo {}
@@ -180,8 +176,8 @@ pub trait Bar {
 }
 ```
 
-If the trait has bounds, there should be a space after the colon but not before
-and before and after each `+`, e.g.,
+If the trait has bounds, put a space after the colon but not before,
+and put spaces around each `+`, e.g.,
 
 ```rust
 trait Foo: Debug + Bar {}
@@ -204,12 +200,11 @@ pub trait IndexRanges:
 }
 ```
 
+## Impls
 
-### Impls
-
-Impl items should be block indented. If there are no items, the impl may be
-formatted on a single line. Otherwise there should be line-breaks after the
-opening brace and before the closing brace:
+Use block-indent for impl items. If there are no items, format the impl
+(including its `{}`) on a single line. Otherwise, break after the opening brace
+and before the closing brace:
 
 ```rust
 impl Foo {}
@@ -231,15 +226,13 @@ impl Bar
 }
 ```
 
-
-### Extern crate
+## Extern crate
 
 `extern crate foo;`
 
 Use spaces around keywords, no spaces around the semicolon.
 
-
-### Modules
+## Modules
 
 ```rust
 mod foo {
@@ -253,7 +246,7 @@ mod foo;
 Use spaces around keywords and before the opening brace, no spaces around the
 semicolon.
 
-### macro\_rules!
+## `macro_rules!`
 
 Use `{}` for the full definition of the macro.
 
@@ -262,17 +255,16 @@ macro_rules! foo {
 }
 ```
 
-
-### Generics
+## Generics
 
 Prefer to put a generics clause on one line. Break other parts of an item
 declaration rather than line-breaking a generics clause. If a generics clause is
-large enough to require line-breaking, you should prefer to use a `where` clause
-instead.
+large enough to require line-breaking, prefer a `where` clause instead.
 
-Do not put spaces before or after `<` nor before `>`. Only put a space after `>`
-if it is followed by a word or opening brace, not an opening parenthesis. There
-should be a space after each comma and no trailing comma.
+Do not put spaces before or after `<` nor before `>`. Only put a space after
+`>` if it is followed by a word or opening brace, not an opening parenthesis.
+Put a space after each comma. Do not use a trailing comma for a single-line
+generics clause.
 
 ```rust
 fn foo<T: Display, U: Debug>(x: Vec<T>, y: Vec<U>) ...
@@ -280,10 +272,9 @@ fn foo<T: Display, U: Debug>(x: Vec<T>, y: Vec<U>) ...
 impl<T: Display, U: Debug> SomeType<T, U> { ...
 ```
 
-If the generics clause must be formatted across multiple lines, each parameter
-should have its own block-indented line, there should be newlines after the
-opening bracket and before the closing bracket, and the should be a trailing
-comma.
+If the generics clause must be formatted across multiple lines, put each
+parameter on its own block-indented line, break after the opening `<` and
+before the closing `>`, and use a trailing comma.
 
 ```rust
 fn foo<
@@ -292,8 +283,7 @@ fn foo<
 >(x: Vec<T>, y: Vec<U>) ...
 ```
 
-If an associated type is bound in a generic type, then there should be spaces on
-either side of the `=`:
+If an associated type is bound in a generic type, put spaces around the `=`:
 
 ```rust
 <T: Example<Item = u32>>
@@ -301,17 +291,18 @@ either side of the `=`:
 
 Prefer to use single-letter names for generic parameters.
 
-
-### `where` clauses
+## `where` clauses
 
 These rules apply for `where` clauses on any item.
 
-A `where` clause may immediately follow a closing bracket of any kind.
-Otherwise, it must start a new line, with no indent. Each component of a `where`
-clause must be on its own line and be block indented. There should be a trailing
+If immediately following a closing bracket of any kind, write the keyword
+`where` on the same line, with a space before it.
+
+Otherwise, put `where` on a new line at the same indentation level. Put each
+component of a `where` clause on its own line, block-indented. Use a trailing
 comma, unless the clause is terminated with a semicolon. If the `where` clause
-is followed by a block (or assignment), the block should be started on a new
-line. Examples:
+is followed by a block (or assignment), start that block on a new line.
+Examples:
 
 ```rust
 fn function<T, U>(args)
@@ -355,12 +346,12 @@ where
 = Bar<T>;
 ```
 
-If a `where` clause is very short, we recommend using an inline bound on the
-type parameter.
-
+If a `where` clause is very short, prefer using an inline bound on the type
+parameter.
 
-If a component of a `where` clause is long, it may be broken before `+` and
-further block indented. Each bound should go on its own line. E.g.,
+If a component of a `where` clause does not fit and contains `+`, break it
+before each `+` and block-indent the continuation lines. Put each bound on its
+own line. E.g.,
 
 ```rust
 impl<T: ?Sized, Idx> IndexRanges<Idx> for T
@@ -369,40 +360,14 @@ where
         + Index<RangeTo<Idx>, Output = Self::Output>
         + Index<RangeFrom<Idx>, Output = Self::Output>
         + Index<RangeInclusive<Idx>, Output = Self::Output>
-        + Index<RangeToInclusive<Idx>, Output = Self::Output> + Index<RangeFull>
+        + Index<RangeToInclusive<Idx>, Output = Self::Output>
+        + Index<RangeFull>,
 ```
 
-#### Option - `where_single_line`
+## Type aliases
 
-`where_single_line` is `false` by default. If `true`, then a where clause with
-exactly one component may be formatted on a single line if the rest of the
-item's signature is also kept on one line. In this case, there is no need for a
-trailing comma and if followed by a block, no need for a newline before the
-block. E.g.,
-
-```rust
-// May be single-lined.
-fn foo<T>(args) -> ReturnType
-where T: Bound {
-    body
-}
-
-// Must be multi-lined.
-fn foo<T>(
-    args
-) -> ReturnType
-where
-    T: Bound,
-{
-    body
-}
-```
-
-
-### Type aliases
-
-Type aliases should generally be kept on one line. If necessary to break the
-line, do so after the `=`; the right-hand-side should be block indented:
+Keep type aliases on one line when they fit. If necessary to break the line, do
+so after the `=`, and block-indent the right-hand side:
 
 ```rust
 pub type Foo = Bar<T>;
@@ -424,29 +389,24 @@ where
 = AnEvenLongerType<T, U, Foo<T>>;
 ```
 
+## Associated types
 
-### Associated types
-
-Associated types should follow the guidelines above for type aliases. Where an
-associated type has a bound, there should be a space after the colon but not
-before:
+Format associated types like type aliases. Where an associated type has a
+bound, put a space after the colon but not before:
 
 ```rust
 pub type Foo: Bar;
 ```
 
+## extern items
 
-### extern items
-
-When writing extern items (such as `extern "C" fn`), always be explicit about
-the ABI. For example, write `extern "C" fn foo ...`, not `extern fn foo ...`, or
+When writing extern items (such as `extern "C" fn`), always specify the ABI.
+For example, write `extern "C" fn foo ...`, not `extern fn foo ...`, or
 `extern "C" { ... }`.
 
+## Imports (`use` statements)
 
-### Imports (`use` statements)
-
-If an import can be formatted on one line, do so. There should be no spaces
-around braces.
+Format imports on one line where possible. Don't put spaces around braces.
 
 ```rust
 use a::b::c;
@@ -454,18 +414,16 @@ use a::b::d::*;
 use a::b::{foo, bar, baz};
 ```
 
-
-#### Large list imports
+### Large list imports
 
 Prefer to use multiple imports rather than a multi-line import. However, tools
-should not split imports by default (they may offer this as an option).
+should not split imports by default.
 
 If an import does require multiple lines (either because a list of single names
 does not fit within the max width, or because of the rules for nested imports
 below), then break after the opening brace and before the closing brace, use a
 trailing comma, and block indent the names.
 
-
 ```rust
 // Prefer
 foo::{long, list, of, imports};
@@ -478,8 +436,7 @@ foo::{
 };
 ```
 
-
-#### Ordering of imports
+### Ordering of imports
 
 A *group* of imports is a set of imports on the same or sequential lines. One or
 more blank lines or other items (e.g., a function) separate groups of imports.
@@ -487,7 +444,6 @@ more blank lines or other items (e.g., a function) separate groups of imports.
 Within a group of imports, imports must be sorted ASCIIbetically (uppercase
 before lowercase). Groups of imports must not be merged or re-ordered.
 
-
 E.g., input:
 
 ```rust
@@ -511,29 +467,25 @@ use b;
 Because of `macro_use`, attributes must also start a new group and prevent
 re-ordering.
 
-#### Ordering list import
+### Ordering list import
 
 Names in a list import must be sorted ASCIIbetically, but with `self` and
 `super` first, and groups and glob imports last. This applies recursively. For
 example, `a::*` comes before `b::a` but `a::b` comes before `a::*`. E.g.,
 `use foo::bar::{a, b::c, b::d, b::d::{x, y, z}, b::{self, r, s}};`.
 
+### Normalisation
 
-#### Normalisation
-
-Tools must make the following normalisations:
-
-* `use a::self;` -> `use a;`
-* `use a::{};` -> (nothing)
-* `use a::{b};` -> `use a::b;`
+Tools must make the following normalisations, recursively:
 
-And must apply these recursively.
+- `use a::self;` -> `use a;`
+- `use a::{};` -> (nothing)
+- `use a::{b};` -> `use a::b;`
 
 Tools must not otherwise merge or un-merge import lists or adjust glob imports
 (without an explicit option).
 
-
-#### Nested imports
+### Nested imports
 
 If there are any nested imports in a list import, then use the multi-line form,
 even if the import fits on one line. Each nested import must be on its own line,
@@ -549,8 +501,7 @@ use a::b::{
 };
 ```
 
-
-#### Merging/un-merging imports
+### Merging/un-merging imports
 
 An example:
 
diff --git a/src/doc/style-guide/src/nightly.md b/src/doc/style-guide/src/nightly.md
index 031811b0e..66e7fa3c9 100644
--- a/src/doc/style-guide/src/nightly.md
+++ b/src/doc/style-guide/src/nightly.md
@@ -1,3 +1,5 @@
+# Nightly
+
 This chapter documents style and formatting for nightly-only syntax. The rest of the style guide documents style for stable Rust syntax; nightly syntax only appears in this chapter. Each section here includes the name of the feature gate, so that searches (e.g. `git grep`) for a nightly feature in the Rust repository also turn up the style guide section.
 
 Style and formatting for nightly-only syntax should be removed from this chapter and integrated into the appropriate sections of the style guide at the time of stabilization.
diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md
index d548693e3..ce57c649a 100644
--- a/src/doc/style-guide/src/principles.md
+++ b/src/doc/style-guide/src/principles.md
@@ -3,27 +3,27 @@
 When deciding on style guidelines, the style team follows these guiding
 principles (in rough priority order):
 
-* readability
-    - scan-ability
-    - avoiding misleading formatting
-    - accessibility - readable and editable by users using the widest
-      variety of hardware, including non-visual accessibility interfaces
-    - readability of code in contexts without syntax highlighting or IDE
-      assistance, such as rustc error messages, diffs, grep, and other
-      plain-text contexts
+- readability
+  - scan-ability
+  - avoiding misleading formatting
+  - accessibility - readable and editable by users using the widest
+    variety of hardware, including non-visual accessibility interfaces
+  - readability of code in contexts without syntax highlighting or IDE
+    assistance, such as rustc error messages, diffs, grep, and other
+    plain-text contexts
 
-* aesthetics
-    - sense of 'beauty'
-    - consistent with other languages/tools
+- aesthetics
+  - sense of 'beauty'
+  - consistent with other languages/tools
 
-* specifics
-    - compatibility with version control practices - preserving diffs,
-      merge-friendliness, etc.
-    - preventing rightward drift
-    - minimising vertical space
+- specifics
+  - compatibility with version control practices - preserving diffs,
+    merge-friendliness, etc.
+  - preventing rightward drift
+  - minimising vertical space
 
-* application
-    - ease of manual application
-    - ease of implementation (in `rustfmt`, and in other tools/editors/code generators)
-    - internal consistency
-    - simplicity of formatting rules
+- application
+  - ease of manual application
+  - ease of implementation (in `rustfmt`, and in other tools/editors/code generators)
+  - internal consistency
+  - simplicity of formatting rules
diff --git a/src/doc/style-guide/src/statements.md b/src/doc/style-guide/src/statements.md
index a5cd6da10..6f322b3d6 100644
--- a/src/doc/style-guide/src/statements.md
+++ b/src/doc/style-guide/src/statements.md
@@ -1,9 +1,9 @@
-## Statements
+# Statements
 
-### Let statements
+## Let statements
 
-There should be spaces after the `:` and on both sides of the `=` (if they are
-present). No space before the semicolon.
+Put a space after the `:` and on both sides of the `=` (if they are present).
+Don't put a space before the semicolon.
 
 ```rust
 // A comment.
@@ -14,20 +14,19 @@ let pattern: Type;
 let pattern = expr;
 ```
 
-If possible the declaration should be formatted on a single line. If this is not
-possible, then try splitting after the `=`, if the declaration can fit on two
-lines. The expression should be block indented.
+If possible, format the declaration on a single line. If not possible, then try
+splitting after the `=`, if the declaration fits on two lines. Block-indent the
+expression.
 
 ```rust
 let pattern: Type =
     expr;
 ```
 
-If the first line does not fit on a single line, then split after the colon,
-using block indentation. If the type covers multiple lines, even after line-
-breaking after the `:`, then the first line may be placed on the same line as
-the `:`, subject to the [combining rules](https://github.com/rust-lang-nursery/fmt-rfcs/issues/61) (WIP).
-
+If the first line still does not fit on a single line, split after the `:`, and
+use block indentation. If the type requires multiple lines, even after
+line-breaking after the `:`, then place the first line on the same line as the
+`:`, subject to the [combining rules](expressions.html#combinable-expressions).
 
 ```rust
 let pattern:
@@ -51,12 +50,12 @@ let (abcd,
 ```
 
 If the expression covers multiple lines, if the first line of the expression
-fits in the remaining space, it stays on the same line as the `=`, the rest of the
-expression is not indented. If the first line does not fit, then it should start
-on the next lines, and should be block indented. If the expression is a block
-and the type or pattern cover multiple lines, then the opening brace should be
-on a new line and not indented (this provides separation for the interior of the
-block from the type), otherwise the opening brace follows the `=`.
+fits in the remaining space, it stays on the same line as the `=`, and the rest
+of the expression is not further indented. If the first line does not fit, then
+put the expression on subsequent lines, block indented. If the expression is a
+block and the type or pattern cover multiple lines, put the opening brace on a
+new line and not indented (this provides separation for the interior of the
+block from the type); otherwise, the opening brace follows the `=`.
 
 Examples:
 
@@ -101,15 +100,15 @@ let Foo {
 );
 ```
 
-#### else blocks (let-else statements)
+### else blocks (let-else statements)
 
 A let statement can contain an `else` component, making it a let-else statement.
 In this case, always apply the same formatting rules to the components preceding
 the `else` block (i.e. the `let pattern: Type = initializer_expr` portion)
 as described [for other let statements](#let-statements).
 
-The entire let-else statement may be formatted on a single line if all the
-following are true:
+Format the entire let-else statement on a single line if all the following are
+true:
 
 * the entire statement is *short*
 * the `else` block contains only a single-line expression and no statements
@@ -120,9 +119,6 @@ following are true:
 let Some(1) = opt else { return };
 ```
 
-Formatters may allow users to configure the value of the threshold
-used to determine whether a let-else statement is *short*.
-
 Otherwise, the let-else statement requires some line breaks.
 
 If breaking a let-else statement across multiple lines, never break between the
@@ -157,9 +153,9 @@ before the `else`.
     };
 ```
 
-If the initializer expression is multi-line, the `else` keyword and opening
-brace of the block (i.e. `else {`) should be put on the same line as the end of
-the initializer expression, with a space between them, if and only if all the
+If the initializer expression is multi-line, put the `else` keyword and opening
+brace of the block (i.e. `else {`) on the same line as the end of the
+initializer expression, with a space between them, if and only if all the
 following are true:
 
 * The initializer expression ends with one or more closing
@@ -182,9 +178,9 @@ let Some(x) = y.foo(
 }
 ```
 
-Otherwise, the `else` keyword and opening brace should be placed on the next
-line after the end of the initializer expression, and the `else` keyword should
-have the same indentation level as the `let` keyword.
+Otherwise, put the `else` keyword and opening brace on the next line after the
+end of the initializer expression, with the `else` keyword at the same
+indentation level as the `let` keyword.
 
 For example:
 
@@ -234,28 +230,27 @@ fn main() {
 }
 ```
 
-### Macros in statement position
+## Macros in statement position
 
-A macro use in statement position should use parentheses or square brackets as
-delimiters and should be terminated with a semicolon. There should be no spaces
-between the name, `!`, the delimiters, or the `;`.
+For a macro use in statement position, use parentheses or square brackets as
+delimiters, and terminate it with a semicolon. Do not put spaces around the
+name, `!`, the delimiters, or the `;`.
 
 ```rust
 // A comment.
 a_macro!(...);
 ```
 
+## Expressions in statement position
 
-### Expressions in statement position
-
-There should be no space between the expression and the semicolon.
+Do not put space between the expression and the semicolon.
 
 ```
 <expr>;
 ```
 
-All expressions in statement position should be terminated with a semicolon,
-unless they end with a block or are used as the value for a block.
+Terminate all expressions in statement position with a semicolon, unless they
+end with a block or are used as the value for a block.
 
 E.g.,
 
diff --git a/src/doc/style-guide/src/types.md b/src/doc/style-guide/src/types.md
index ae456ef21..b7921c891 100644
--- a/src/doc/style-guide/src/types.md
+++ b/src/doc/style-guide/src/types.md
@@ -1,23 +1,22 @@
-## Types and Bounds
+# Types and Bounds
 
-### Single line formatting
+## Single line formatting
 
-* `[T]` no spaces
-* `[T; expr]`, e.g., `[u32; 42]`, `[Vec<Foo>; 10 * 2 + foo()]` (space after colon, no spaces around square brackets)
-* `*const T`, `*mut T` (no space after `*`, space before type)
-* `&'a T`, `&T`, `&'a mut T`, `&mut T` (no space after `&`, single spaces separating other words)
-* `unsafe extern "C" fn<'a, 'b, 'c>(T, U, V) -> W` or `fn()` (single spaces around keywords and sigils, and after commas, no trailing commas, no spaces around brackets)
-* `!` should be treated like any other type name, `Name`
-* `(A, B, C, D)` (spaces after commas, no spaces around parens, no trailing comma unless it is a one-tuple)
-* `<Baz<T> as SomeTrait>::Foo::Bar` or `Foo::Bar` or `::Foo::Bar` (no spaces around `::` or angle brackets, single spaces around `as`)
-* `Foo::Bar<T, U, V>` (spaces after commas, no trailing comma, no spaces around angle brackets)
-* `T + T + T` (single spaces between types, and `+`).
-* `impl T + T + T` (single spaces between keyword, types, and `+`).
+- `[T]` no spaces
+- `[T; expr]`, e.g., `[u32; 42]`, `[Vec<Foo>; 10 * 2 + foo()]` (space after colon, no spaces around square brackets)
+- `*const T`, `*mut T` (no space after `*`, space before type)
+- `&'a T`, `&T`, `&'a mut T`, `&mut T` (no space after `&`, single spaces separating other words)
+- `unsafe extern "C" fn<'a, 'b, 'c>(T, U, V) -> W` or `fn()` (single spaces around keywords and sigils, and after commas, no trailing commas, no spaces around brackets)
+- `!` gets treated like any other type name, `Name`
+- `(A, B, C, D)` (spaces after commas, no spaces around parens, no trailing comma unless it is a one-tuple)
+- `<Baz<T> as SomeTrait>::Foo::Bar` or `Foo::Bar` or `::Foo::Bar` (no spaces around `::` or angle brackets, single spaces around `as`)
+- `Foo::Bar<T, U, V>` (spaces after commas, no trailing comma, no spaces around angle brackets)
+- `T + T + T` (single spaces between types, and `+`).
+- `impl T + T + T` (single spaces between keyword, types, and `+`).
 
-Parentheses used in types should not be surrounded by whitespace, e.g., `(Foo)`
+Do not put space around parentheses used in types, e.g., `(Foo)`
 
-
-### Line breaks
+## Line breaks
 
 Avoid breaking lines in types where possible. Prefer breaking at outermost scope, e.g., prefer
 
@@ -37,13 +36,17 @@ Foo<Bar, Baz<
 >>
 ```
 
-`[T; expr]` may be broken after the `;` if necessary.
+If a type requires line-breaks in order to fit, this section outlines where to
+break such types if necessary.
+
+Break `[T; expr]` after the `;` if necessary.
 
-Function types may be broken following the rules for function declarations.
+Break function types following the rules for function declarations.
 
-Generic types may be broken following the rules for generics.
+Break generic types following the rules for generics.
 
-Types with `+` may be broken after any `+` using block indent and breaking before the `+`. When breaking such a type, all `+`s should be line broken, e.g.,
+Break types with `+` by breaking before the `+` and block-indenting the
+subsequent lines. When breaking such a type, break before *every* `+`:
 
 ```rust
 impl Clone