diff options
| -rw-r--r-- | src/doc/style-guide/src/README.md | 6 | ||||
| -rw-r--r-- | src/doc/style-guide/src/SUMMARY.md | 16 | ||||
| -rw-r--r-- | src/doc/style-guide/src/advice.md | 16 | ||||
| -rw-r--r-- | src/doc/style-guide/src/expressions.md | 6 | ||||
| -rw-r--r-- | src/doc/style-guide/src/items.md | 6 | ||||
| -rw-r--r-- | src/doc/style-guide/src/nightly.md | 2 | ||||
| -rw-r--r-- | src/doc/style-guide/src/principles.md | 34 | ||||
| -rw-r--r-- | src/doc/style-guide/src/types.md | 22 |
8 files changed, 55 insertions, 53 deletions
diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md index d9214d0da83..f4d75967370 100644 --- a/src/doc/style-guide/src/README.md +++ b/src/doc/style-guide/src/README.md @@ -36,10 +36,10 @@ options. ### Indentation and line width -* Use spaces, not tabs. -* Each level of indentation must be 4 spaces (that is, all indentation +- 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. +- The maximum width for a line is 100 characters. #### Block indent diff --git a/src/doc/style-guide/src/SUMMARY.md b/src/doc/style-guide/src/SUMMARY.md index 231bcdf7099..606485bfb6c 100644 --- a/src/doc/style-guide/src/SUMMARY.md +++ b/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) diff --git a/src/doc/style-guide/src/advice.md b/src/doc/style-guide/src/advice.md index 717bae2a3d6..65cf8cb6e90 100644 --- a/src/doc/style-guide/src/advice.md +++ b/src/doc/style-guide/src/advice.md @@ -18,14 +18,14 @@ 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`), +- 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`). diff --git a/src/doc/style-guide/src/expressions.md b/src/doc/style-guide/src/expressions.md index c4f5491ff79..32c604f9f3e 100644 --- a/src/doc/style-guide/src/expressions.md +++ b/src/doc/style-guide/src/expressions.md @@ -63,10 +63,10 @@ Write an empty block as `{}`. Write a block on a single line if: -* it is either used in expression position (not statement position) or is an +- 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 +- it contains a single-line expression and no statements, and +- it contains no comments For a single-line block, put spaces after the opening brace and before the closing brace. diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index f9bee3fb900..a6d941f6d04 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -478,9 +478,9 @@ example, `a::*` comes before `b::a` but `a::b` comes before `a::*`. E.g., Tools must make the following normalisations, recursively: -* `use a::self;` -> `use a;` -* `use a::{};` -> (nothing) -* `use a::{b};` -> `use a::b;` +- `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). diff --git a/src/doc/style-guide/src/nightly.md b/src/doc/style-guide/src/nightly.md index 031811b0e6f..66e7fa3c9f8 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 379a99ead48..ce57c649a2d 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 +- 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 + - 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, +- specifics + - compatibility with version control practices - preserving diffs, merge-friendliness, etc. - * preventing rightward drift - * minimising vertical space + - 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/types.md b/src/doc/style-guide/src/types.md index 586a86f18a6..b7921c8914e 100644 --- a/src/doc/style-guide/src/types.md +++ b/src/doc/style-guide/src/types.md @@ -2,17 +2,17 @@ ## 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) -* `!` 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 `+`). +- `[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 `+`). Do not put space around parentheses used in types, e.g., `(Foo)` |