Introduces a "Syntax Index" chapter to TRPL. #28926
Conversation
The intent with this chapter is to have a central place where users can go to find out what a random bit of syntax means, be it a keyword, symbol, or some unusual bit of composite syntax (like `for <...>`). This should be useful both for new users (who may not know what to call this weird `'blah` thing), and for experienced users (who may just wish to link someone to the appropriate section on `Trait + Trait` bounds). Where possible, entries have been linked to an appropriate section of the book which explains the syntax. This was not possible in all cases. If an entry is missing links, that's because I was unable to *find* anything appropriate to link to. This commit should include all stable keywords, operators and symbols, as well as a selection of potentially confusing or unusual syntax.
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @pcwalton (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
|
This is great! When I was beginning to learn Rust I wished there was a list like this. (The reference is a bit long to easily search for stuff.) |
| <!-- Generics --> | ||
|
|
||
| * `path<…>`: specifies parameters to generic type *in a type*. See [Generics]. | ||
| * `path::<…>`: specifies parameters to generic type or function *in an expression*. |
There was a problem hiding this comment.
Maybe expand the example a bit to show this can be used for functions, e.g. "42".parse::<u32>().
* Now mentions method generics. * Has separate entries for generic `fn`, `struct`, `enum`, and `impl` items. (Thanks killercup).
|
I like it. Thanks! |
|
@bors: r+ rollup |
|
📌 Commit b78614f has been approved by |
|
⌛ Testing commit b78614f with merge 54f8381... |
| * `match`: pattern matching. See [Match]. | ||
| * `mod`: module declaration. See [Crates and Modules (Defining Modules)]. | ||
| * `move`: part of closure syntax. See [Closures (`move` closures)]. | ||
| * `mut`: denotes mutability in pointer types, pattern bindings, and `struct` fields. See [Mutability]. |
There was a problem hiding this comment.
s/, and struct fields//
There was a problem hiding this comment.
stares Well, that's embarrassing.
+1, this is very useful |
* removed reference to struct fields from `mut` description. * changed `..` pattern example to not be syntactically bogus. * changed `@` pattern example for similar reasons. (Thanks petrochenkov)
|
@steveklabnik I made some changes prompted by @petrochenkov's comments; hope that doesn't stuff anything up. Good bors pats |
|
@bors: r+ rollup |
|
📌 Commit 2b59834 has been approved by |
|
Would it be worth it to add keywords that are reserved but not used (like |
|
@aochagavia I decided against it on the basis that doing so can only confuse things. Such keywords can't show up in existing code and can't be used in new code. It'd be a bit like having keywords from unrelated languages with the note "not used in Rust at all in any way". That said, it just occurred to me that you could make an argument for obsolete syntax. We do have a bit of an issue with old code examples, so maybe it'd be worth listing old syntax at the end. But not in this PR. I don't want to create even more work for poor old Bors. throws Bors a cookie |
Shouldn't those be "ident" not "expr"? |
|
@DanielKeep I'd be interested in noting reserved (and deprecated) things, as code doesn't clearly indicate what version it works with. If you see |
|
⌛ Testing commit 2b59834 with merge d0813b9... |
|
|
|
@gankro My concern was that, for example, it's possible that Maybe there's a use for stuff in nightly that hasn't made it to stable yet, though. |
|
@Diggsey That's because I couldn't find any documentation on higher ranked lifetime syntax in the book. |
|
💔 Test failed - auto-mac-32-opt |
|
Yes, there's a bug open for adding HRTB |
|
@bors: retry On Fri, Oct 9, 2015 at 10:47 AM, Steve Klabnik [email protected]
|
|
@DanielKeep nice work 👍. Love it, would end up helping a lot when searching for syntax information quickly. |
|
@Diggsey it just seems like all that needs to be done for that is to note when syntax is unstable, no? Edit: there's a degenerate case, I suppose, where syntax is used unstably and then repurposed. |
|
@gankro The |
The intent with this chapter is to have a central place where users can go to find out what a random bit of syntax means, be it a keyword, symbol, or some unusual bit of composite syntax (like `for <...>`). This should be useful both for new users (who may not know what to call this weird `'blah` thing), and for experienced users (who may just wish to link someone to the appropriate section on `Trait + Trait` bounds). Where possible, entries have been linked to an appropriate section of the book which explains the syntax. This was not possible in all cases. If an entry is missing links, that's because I was unable to *find* anything appropriate to link to. This commit should include all stable keywords, operators and symbols, as well as a selection of potentially confusing or unusual syntax.
|
@Diggsey sorry I meant to ping @DanielKeep (dang tab completion!) |
The intent with this chapter is to have a central place where users can
go to find out what a random bit of syntax means, be it a keyword,
symbol, or some unusual bit of composite syntax (like
for <...>). Thisshould be useful both for new users (who may not know what to call this
weird
'blahthing), and for experienced users (who may just wish tolink someone to the appropriate section on
Trait + Traitbounds).Where possible, entries have been linked to an appropriate section of
the book which explains the syntax. This was not possible in all cases.
If an entry is missing links, that's because I was unable to find
anything appropriate to link to.
This commit should include all stable keywords, operators and symbols,
as well as a selection of potentially confusing or unusual syntax.