Repository navigation
Add documentation for all keywords like the primitive types' documentation #34601
Description
Here's what I would like to be able to do:
- Visit http://doc.rust-lang.org/std/
- In the search box, type any keyword, such as
match - Get back comprehensive documentation about
match'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, i32 and pointer will return results but match and where will not?
I'm going to research how the primitive types are documented, but wanted to file this for discussion purposes in the meantime.
Activity
brson commentedon Jul 1, 2016
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.
GuillaumeGomez commentedon Jul 2, 2016
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?
carols10cents commentedon Jul 2, 2016
But this info is being removed from the book, it should go somewhere else.
On Jul 2, 2016 8:09 AM, "Guillaume Gomez" notifications@github.com wrote:
GuillaumeGomez commentedon Jul 2, 2016
Really? That complicates things a bit. We should then create a glossary for keywords.
GuillaumeGomez commentedon Jul 2, 2016
And while I think about it: cc @steveklabnik
GuillaumeGomez commentedon May 23, 2018
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
cc @rust-lang/rustdoc
63 remaining items
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73867 - poliorcetics:union-keyword, r=josht…
Rollup merge of rust-lang#73762 - poliorcetics:trait-keyword, r=KodrAus
Rollup merge of rust-lang#73618 - poliorcetics:false-keyword, r=jyn514
Rollup merge of rust-lang#73618 - poliorcetics:false-keyword, r=jyn514
Auto merge of rust-lang#73645 - poliorcetics:ref-keyword, r=jyn514
Auto merge of rust-lang#74017 - poliorcetics:where-keyword, r=jyn514
poliorcetics commentedon Jul 25, 2020
The last PR for this is #73943 (unsafe keyword), after that it will be done !
Rollup merge of rust-lang#73943 - poliorcetics:unsafe-keyword, r=stev…