Move punctuation index to an appendix, and expand for other syntaxes #2061
+465
−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".
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