Move punctuation index to an appendix, and expand for other syntaxes #2061
+474
−102
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This adds a new appendix caled "Syntax index" which is an index of various syntactical elements of the language. This initial commit just moves the index of punctuation symbols as-is without modification.
This adjusts the capitalization just because I felt the mixed and inconsistent capitalization looked odd, and it felt simpler to just keep it lowercase. I also didn't feel like there was a particular need to sentence case these.
None of the other lists use "and" for the final element. I'm not sure why this was here.
This adds a pipe at the end of the line because it is the recommended style for gfm tables.
The pipe symbol wasn't updated when or-patterns were stabilized. This updates it for that new grammar.
When use bounds were stabilized, I forgot to add the angle brackets to the index.
This adds let statements to the `=` index entry. It really is distinct from assignment, and I probably just overlooked that.
This switches all the links to rule links for consistency. It's easier to link to specific rules this way. Some of the links were adjusted to go to more specific rules.
This pollutes the search index, since the reader probably wants to go to the things that these point to.
Unfortunately the comments chapter isn't organized in a way that it is easy to link to specific kinds of comments.
rustbot
added
the
S-waiting-on-review
"The inferred type" and "the wildcard pattern" are singular things. Let's not pluralize these.
We have now not just the inferred type but also the inferred const, so let's include that in the syntax index.
The placeholder lifetime is the lifetime equivalent of the inferred const and the inferred type (and, in fact, we should probably rename it to the inferred lifetime). Let's mention it alongside these similar things in the syntax index. We could ask whether it should really appear in the "type expressions" section. After all, it's not exactly a type expression. However, neither is `for<...>`, but that appears in this section. We can justify both by observing that they may appear within `impl Trait` and `dyn Trait` -- and these are type expressions.
traviscross
force-pushed
the
syntax-index
branch
6 times, most recently
from
1ec735f to
6a61838
Compare
traviscross
approved these changes
Oct 28, 2025
In the patterns section of the syntax index, we had listed other kinds of patterns, and we had listed `..` for rest patterns, but we hadn't noted its use for range patterns or listed `..=`. Let's do that.
The text referred to `_` as applying to "unnamed items in constants", but this doesn't really speak to me. Let's say instead, "unnamed constant items".
We had described `as` as applying to an "extern crate alias" or "use alias". While I gather the meaning, and we do use this term in some code examples, I'm not sure in the index we'd necessarily want to treat these as canonical names. The term "use alias" seems particularly tenuous; I'd probably at least say, e.g. "use declaration alias" or "use item alias" or similar. Other items in the list often just refer to the top-level feature; let's do that here. We'll keep (and inline) the link to the specific section.
We had listed many other things as being related to `unsafe`, but not unsafe blocks, so let's list those.
For the semicolon, we had listed "array types", but we had not listed "array expressions" even though the semicolon is used for those as well. Let's add that.
For `->`, we had listed "function return type" and "closure return type". For me, I read this table as "the thing on the left is used in the thing on the right". But that's not really true here; the `->` is not used *in* the function or closure return type. It's probably better just to say that `->` is used in functions and closures, so let's do that.
For `#`, we had noted that it was used in attributes, but it's also used in raw string literals, raw byte string literals, and raw C string literals, so let's list those as well.
For `?`, in this branch, we had listed "questionably sized" in the syntax index. I'm not a fan of this terminology. As I wrote elsewhere, in Rust PR 145924: > I don't think we should use the word "maybe" to refer to "?X" bound > relaxations. Either there's a predicate stating that a type > parameter implements some trait or there isn't. While of course I > get it -- the type argument provided may or may not implement the > trait -- I just think "maybe" is speaking to the wrong thing here. > It focuses on the type argument when what makes more sense to focus > on is the type parameter. And the type parameter is not in a > "maybe" state. In this regard, I feel the same about "questionably" as I do "maybe". We don't use this terminology elsewhere in the Reference, so let's not use it here. Let's instead refer simply to "relaxed trait bounds", as we do elsewhere in the syntax index.
In writing RFC 3531, I came to believe that the most correct fully qualified term for what `kind` is in `$ident:kind` is a "macro matcher fragment specifier", and I still think that's right. It's unfortunate that it's such a mouthful, but let's use that term in the syntax index.
On the branch, in the syntax index, we had called `$ident` a "macro fragment substitution". The way that I think about it is that `$ident` is a macro metavariable that is bound to a fragment. That is, the metavariable is the parameter while the fragment is the argument. That's why a "macro matcher fragment specifier" makes sense -- we're specifying the kind of the fragment that can be bound to this macro metavariable in the matcher. In this light, let's call `$ident` simply a "macro metavariable" in the syntax index.
In closures without an ascribed return type, an expression follows the vertical bars. In closures with an ascribed return type, a block follows. Let's add this second syntax to the syntax index.
Elsewhere in this table, we spell `Type` and `Trait` in uppercase, so let's do that here as well.
On the branch, we had an entry in the expressions table for `Type<ident=Type>`. This was notated as "explicit associated type bounds" and referenced a TODO item about default type parameters not being documented. Perhaps what this means to describe are associated type bindings and associated type bounds. Let's document those in the type expressions table. We'll remove the TODO note, as it's not relevant to this.
The syntax `Type<..>`, without turbofish, is only valid in a type expression. Let's move this to that table and document `Trait<..>` along with it.
On the branch, we had pluralized other related expressions, so let's also pluralize "single element tuple expressions".
For macro invocations, struct expressions, and struct patterns, we had shown the opening curly brace without a space in front of it. This can make it visually difficult to distinguish from an opening parenthesis. Using the common Rust style of putting a space in front helps with that, so let's do that here.
On the branch, in the syntax index, items were described as "declarations in a crate". Some items may be declarations, but many items are actually definitions. It's probably better to not use either term here. Let's instead say that items are the components of a crate as that's the language that's used in the items chapter.
On the branch, in the index, in the table for items, we had written `mod ident;` and `use path;` but we hadn't similarly indicated a trailing semicolon for type aliases, const items, and static items. Let's be consistent and indicate the trailing semicolon for those.
traviscross
force-pushed
the
syntax-index
branch
from
6a61838 to
a2b6ab5
Compare
ehuss
commented
Oct 28, 2025
In the syntax index, in the type expressions table, we list some primitive types but not all of them. Let's use the ellipses to indicate that the list is not exhaustive.
On the branch, the syntax index had used "compound type bounds" to refer to a bound with a `+` in it. This isn't a term we use elsewhere; let's not use it here.
On the branch, in the syntax index, we had notated a slice type so as to include a type and then ellipses, but it's more correct for a slice type to just have a type in the square brackets, so let's do that.
In the syntax index, in a list of things to which type paths can refer, let's refer to "type aliases" rather than just to "aliases" for better clarity.
In the syntax index, in the table about type expressions, we have a list of things that can be referred to by type paths. Let's link to each of the items in that list.
Like "the wildcard pattern", there is only one "rest pattern". Let's singularize this and add the appropriate redirect.
In the keywords table in the syntax index, every entry except the one for constant items for `_` consists entirely of a link body. For that one, though, we had left "unnamed" out of the link body. Visually, that just stands out too much. We could just put "unnamed" in the link body, but most of the other entries aren't really that specific. It seems OK to just say "constant items" for this, so let's do that.
In each table in the syntax index, we have some bit of syntax on the left and then on the right we have features in which that bit of syntax is used. Should we title the column on the right "use" (or maybe "uses") or "usage"? One could almost, superficially, make a case for "usage". As relevant here, Webster's defines it as "the way in which a word, phrase, etc. is used to express a particular idea". That sounds close. The trouble is that it's nearly the wrong way around. The "idea" here is actually the thing on the right. The "usage" would be the place or way in which the syntax is used to express that idea. Conversely, definitions of "use" apply cleanly: to "employ for or apply to a given purpose", "an instance or way of using", etc. As Garner says: > Whenever *use* is possible, *usage* shouldn't appear. Let's say "use".
traviscross
force-pushed
the
syntax-index
branch
from
a2b6ab5 to
e93dce5
Compare
rustbot
removed
the
S-waiting-on-review
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds a new syntax index which shows some common, potentially hard-to-search syntax examples along with links to the definitions for those forms.
This is based on the syntax index that is in the book (https://doc.rust-lang.org/1.90.0/book/appendix-02-operators.html). There have been occasional requests for this, with links in the reference.
I decided to organize it by concepts instead of by syntax. For example
(…)could be a grouped expression, type, or pattern. However, I think the amount of overlap between concepts is small, and I liked the idea of emphasizing the distinction of these concepts to really convey that they should not be conflated. But I would also be open to a more syntax-based organization.This is not intended to be 100% exhaustive. There are many permutations and qualifiers, and I felt it would just make the list too long to try to cover everything.
Closes #211