Add documentation for all keywords like the primitive types' documentation #34601
Comments
|
It's hard for me to see how this fits into rustdoc, since rustdoc is primarily for documenting APIs (the primitives are a special case since they could be library types). This seems to call for a more integrated set of documentation that is searchable and cross-referable across sources. Which would be great. |
brson
added
T-rustdoc
|
It's indeed difficult to see how it could be integrated. Maybe an hybrid system: if some specific keywords are entered, we propose a link to the corresponding chapter of The Book? |
|
But this info is being removed from the book, it should go somewhere else.
|
|
Really? That complicates things a bit. We should then create a glossary for keywords. |
|
And while I think about it: cc @steveklabnik |
steveklabnik
added
T-tools
A-docs
steveklabnik
added
T-dev-tools
Mark-Simulacrum
added
the
C-enhancement
|
So what should we do about it? I extended docs search quite a bit so at this point, I think we could create something similar that for primitives (ie, a tag and then you put your doc on it), and then we'd be mostly done (just a bit of design to conclude). Does that sound good to everyone? cc @rust-lang/docs |
|
We already have a way to tag docs onto a thing that doesn't have an item associated with it. The primitive pages all work by using a special attribute on an empty module, so we can easily cook up a similar |
|
I'll work on adding the keyword pages first then. For the documentation, I may be not the best to write it. |
|
I'm going to be honest, I not really a fan of this. Keywords aren't like anything else that rustdoc documents so it seems weird to shoehorn them in. Maybe what we really need is a combined search which covers the |
rustdoc: introduce the #[doc(keyword="")] attribute for documenting keywords Part of #34601. r? @QuietMisdreavus
…Misdreavus Add let keyword doc Part of rust-lang#34601.
…Misdreavus Add let keyword doc Part of rust-lang#34601. r? @rust-lang/docs
|
@GuillaumeGomez @steveklabnik I guess this issue is kind of resolved? I checked the Rust docs here and I see that you can already search for keywords ( I guess that means we can close this issue now? I did however found out that there are quite some keywords that do now have documentation yet. I went through the entire list of reserved keywords and these do currently not have any documentation. Keywords:
Reserved for Future Use:
Personally I wonder if keywords like |
|
There actually already is a tracking issue for this: #51451. I don't know why both of these issues are open. FWIW I still don't think adding these docs to the |
|
@ollie27 Ahh I guess we can close this one now then. I do think we at least make it more clear somehow that you can also search for keywords there. I mean currently it feels like you can only search for stdlib documentation there, but not for actual keywords. |
Document the type keyword Partial fix of rust-lang#34601. Two small examples, one clarifying that `type` only defines an alias, not a completely new type, the other explaining the use in traits. @rustbot modify labels: T-doc,C-enhancement
…sKalbertodt Document the static keyword Partial fix of rust-lang#34601. This documents the `static` keyword. It's basically a simplified version of the reference with more examples. @rustbot modify labels: T-doc,C-enhancement
Document the type keyword Partial fix of rust-lang#34601. Two small examples, one clarifying that `type` only defines an alias, not a completely new type, the other explaining the use in traits. @rustbot modify labels: T-doc,C-enhancement
…sKalbertodt Document the static keyword Partial fix of rust-lang#34601. This documents the `static` keyword. It's basically a simplified version of the reference with more examples. @rustbot modify labels: T-doc,C-enhancement
Document the type keyword Partial fix of rust-lang#34601. Two small examples, one clarifying that `type` only defines an alias, not a completely new type, the other explaining the use in traits. @rustbot modify labels: T-doc,C-enhancement
…sKalbertodt Document the static keyword Partial fix of rust-lang#34601. This documents the `static` keyword. It's basically a simplified version of the reference with more examples. @rustbot modify labels: T-doc,C-enhancement
Document the type keyword Partial fix of rust-lang#34601. Two small examples, one clarifying that `type` only defines an alias, not a completely new type, the other explaining the use in traits. @rustbot modify labels: T-doc,C-enhancement
…sKalbertodt Document the static keyword Partial fix of rust-lang#34601. This documents the `static` keyword. It's basically a simplified version of the reference with more examples. @rustbot modify labels: T-doc,C-enhancement
Document the type keyword Partial fix of rust-lang#34601. Two small examples, one clarifying that `type` only defines an alias, not a completely new type, the other explaining the use in traits. @rustbot modify labels: T-doc,C-enhancement
…sKalbertodt Document the static keyword Partial fix of rust-lang#34601. This documents the `static` keyword. It's basically a simplified version of the reference with more examples. @rustbot modify labels: T-doc,C-enhancement
Document the type keyword Partial fix of rust-lang#34601. Two small examples, one clarifying that `type` only defines an alias, not a completely new type, the other explaining the use in traits. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
…riplett Document the union keyword Partial fix of rust-lang#34601. This documents the `union` keyword by presenting three cases: simply using a union, matching on a union and referencing the fields of a union. @rustbot modify labels: T-doc,C-enhancement
Document the trait keyword Partial fix of rust-lang#34601. This document the trait keyword. To avoid doing too much and forcing more updates as functionalities evolve, I put two links to the reference, especially for trait objects. This mainly documents the "big" parts, not so much the small details that might trip someone experimenting. @rustbot modify labels: T-doc,C-enhancement
Documentation for the false keyword Partial fix of rust-lang#34601. Short documentation for the false keyword mainly pointing to the `true` keyword.
Documentation for the false keyword Partial fix of rust-lang#34601. Short documentation for the false keyword mainly pointing to the `true` keyword.
Document the ref keyword Partial fix for rust-lang#34601. This documents the `ref` keyword with two examples, one failing to compile because the `ref` keyword is missing, and the same example fixed with the keyword inserted in the correct place. It also explains (very *very* rapidly) the differences between `&` and `ref`. I put a link to the best place I could find in the Reference but there may be something better that I didn't find.
Document the where keyword Partial fix of rust-lang#34601 (and last PR for it 🎉). This documents the `where` keyword. @rustbot modify labels: T-doc,C-enhancement
|
The last PR for this is #73943 (unsafe keyword), after that it will be done ! |
Here's what I would like to be able to do:
matchmatch's functionality, similar to the documentation for the primitive types (ex: pointer)For unused but reserved keywords, I would expect to see something along the lines of "This keyword has no current functionality but is reserved for Rust to possibly use in the future."
Why this is important
Currently, all the details about pattern matching syntax is only documented in the book, as far as I can tell. In the new version of the book, we're moving away from trying to be comprehensive towards just covering the most important, most commonly used constructs. But if we remove documentation about, say, the precedence of
|and match guards, where will people go to learn about it? (The Reference doesn't have anything about that stuff either).Furthermore, how is a new rustacean supposed to know that, say,
i32andpointerwill return results butmatchandwherewill not?I'm going to research how the primitive types are documented, but wanted to file this for discussion purposes in the meantime.
The text was updated successfully, but these errors were encountered: