Move punctuation index to an appendix, and expand for other syntaxes #2061
+467
−98
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.
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 the top-level feature; let's do that here. We'll keep (and inline) the link to the specific section.
While we do prefer to use the plural, the plural for "extern crate" would be "extern crate declarations". In lieu of that, let's just say "extern crate" as that's reminiscent of the syntax.
The plural of "impl trait" is "impl trait types", so let's say that instead of "impl traits". We had already used this elsewhere.
Strictly speaking, use of `impl Trait` in APIT is not an "impl trait type". Let's point "impl trait type" at the entry for RPIT and add a separate item to the index for "anonymous type parameters".
For the `unsafe` keyword, we had noted that it applied to "unsafe static items" and linked to the section that describes how mutable static items must be accessed within an `unsafe` block. Probably this link doesn't make sense. The requirement that an `unsafe` block be used to access mutable statics is just one of the places where an `unsafe` block is required. Conversely, if we mean for this to refer to the syntactic fact that static items can be modified with the `unsafe` keyword, then we'd want to note this as well for the `safe` keyword. However, semantically, we only support these modifiers on external statics, and we already list those separately. So let's just remove "unsafe static items" from the list.
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.
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