Use version-sorting for all sorting
Add a description of a version-sorting algorithm. (This algorithm does
not precisely match `strverscmp`; it's intentionally simpler in its
handling of leading zeroes, and produces a result easier for humans to
easily understand and do by hand.)
Change all references to sorting to use version-sorting.
Change all references to "ASCIIbetically" to instead say "sort
non-lowercase before lowercase".
Treat numeric chunks with equal value but differing numbers of leading
zeroes as equal, unless we get to the end of the entire string in which
case we use "more leading zeroes in the earliest differing chunk" as a
tiebreaker.
Treat `_` as a word separator, sorting it before anything other than
space.
Give more examples.
Amend style guide section for formatting where clauses in type aliases
This PR has two parts:
1. Amend wording about breaking before or after the `=`, which is a style guide bugfix to align it with current rustfmt behavior.
2. Explain how to format trailing (#89122) where clauses, which are preferred in both GATs (#90076) and type aliases (#114662).
r? `@joshtriplett`
style-guide: Document formatting of `as` casts (mostly like a binary operator)
`as` casts currently get formatted like a binary operator, except that
the second line can stack several `as` casts rather than breaking them
each onto their own line. Document this.
As far as I can tell (cc `@calebcartwright` for verification), this is not a 2024 edition change, it just documents current behavior.
Add a description of a version-sorting algorithm. (This algorithm does
not precisely match `strverscmp`; it's intentionally simpler in its
handling of leading zeroes, and produces a result easier for humans to
easily understand and do by hand.)
Change all references to sorting to use version-sorting.
Change all references to "ASCIIbetically" to instead say "sort
non-lowercase before lowercase".
`as` casts currently get formatted like a binary operator, except that
the second line can stack several `as` casts rather than breaking them
each onto their own line. Merge `as` into a subsection of the binary
operators section, and then go into detail on the one difference between
`as` formatting and binary operator formatting.
Improve the rust style guide doc
- Make the levels of headings consistent in this whole document.
Before this change, the highest level of headings in some file is level 1, but in most of the files the that is level 2. Not consistent.
- Fix some headings
- Follow the markdown linter advices
- Remove redundant empty lines
- Surround each heading with empty lines
- Use the same symbol for different levels of unordered list entries
style-guide: Document style editions, start 2024 style edition
Link to a snapshot for the 2015/2018/2021 style edition.
This is a draft, because I'd like to wait for a few style guide fixes to merge
before snapshotting the 2015/2018/2021 style edition:
- https://github.com/rust-lang/rust/pull/113145
- https://github.com/rust-lang/rust/pull/113380
- https://github.com/rust-lang/rust/pull/113384
- https://github.com/rust-lang/rust/pull/113385
- https://github.com/rust-lang/rust/pull/113386
- https://github.com/rust-lang/rust/pull/113392
I'd like to wait for these for two reasons: to make it easier to see the
differences between the 2015/2018/2021 style edition and the 2024 style
edition (without the noise of guide-wide changes), and to minimize confusion so
that bugfixes to the style guide that we include in the previous edition don't
look like they're only part of the 2024 style edition.
I've used "Miscellaneous `rustfmt` bugfixes" as a starting point for the list
of 2024 changes, for now. We can update that when we add more 2024 changes.
The section added in this PR can then serve as a baseline for our drafts of
2024 style edition changes.
In the meantime, I'd like to get someone from `@rust-lang/style` to review and
approve the text here; I'll update it with a commit hash when the above PRs
have merged.
- 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
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.
This is a purely editorial change, and does not affect the semantic
definition of the Rust style.
The style guide requires a trailing comma on where clause components,
but then gives an example that doesn't include one. Add the missing
trailing comma.
style-guide: Fix chain example to match rustfmt behavior
The style guide gave an example of breaking a multi-line chain element
and all subsequent elements to a new line, but that same example and the
accompanying text also had several chain items stacked on the first
line. rustfmt doesn't do this, except when the rule saying to combine
```
shrt
.y()
```
into
```
shrt.y()
```
applies.
This is a bugfix to match rustfmt behavior, so it's not a breaking change, and
it just needs a ``@rust-lang/style`` reviewer to r+.
style-guide: Expand example of combinable expressions to include arrays
Arrays are allowed as combinable expressions, but none of the examples
show that.
