Rollup merge of #113380 - joshtriplett:style-guide-cleanup-must-shoul…

…d-may, r=calebcartwright

style-guide: clean up "must"/"should"/"may"

Avoid using "should" or "may" for required parts of the default style.

The style guide inconsistently used language like "there should be a space" or
"it should be on its own line", or "may be written on a single line", for
things that are required components of the default Rust style. "should" and
especially "may" come across as optional. While the style guide overall now has
a statement at the top that the default style itself is a *recommendation*, the
*definition* of the default style should not be ambiguous about what's part of
the default style.

Rewrite language in the style guide to only use "should" and "may" and similar
for truly optional components of the style (e.g. things a tool cannot or should
not enforce in its default configuration).

In their place, either use "must", or rewrite in imperative style ("put a
space", "start it on the same line"). The latter also substantially reduces the
use of passive voice.

Looking for "should"s also flagged some recommendations the style guide made
for configurability of tools (e.g. a tool "should" have a given configuration
option). I've removed those recommendations, per discussion with the style
team; it's not the domain of the style guide to make such recommendations, only
to define the default Rust style.

In the process of making this change, I also fixed a typo, fixed a text structure
issue, fixed an example that didn't match the Rust style (missing a trailing
comma), and added an additional example for clarity. (Those changes would have
conflicted with this one.) Those changes appear in separate commits.

These are all purely editorial changes, and do not affect the semantic
definition of the Rust style.

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

@@ -40,7 +40,6 @@ options.
 * 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.
 
 #### 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,8 +99,6 @@ 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)
@@ -114,17 +112,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 +171,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 +196,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 +218,7 @@ Foo {
     f2: another_expression(),
 }
 
-// *small* formatting
+// "small" formatting
 Foo { f1, f2 }
 ```
 
@@ -231,10 +231,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)