Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for all keywords like the primitive types' documentation #34601

Closed
carols10cents opened this issue Jul 1, 2016 · 21 comments · Fixed by #73943
Closed

Add documentation for all keywords like the primitive types' documentation #34601

carols10cents opened this issue Jul 1, 2016 · 21 comments · Fixed by #73943
Assignees
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. P-medium Medium priority T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@carols10cents
Copy link
Member

carols10cents commented Jul 1, 2016

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.

@brson
Copy link
Contributor

brson commented 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.

@brson brson added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-docs labels Jul 1, 2016
@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented 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
Copy link
Member Author

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:

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?


You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#34601 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAL1UnG-QLzUWxE5_QBv4yZrYsbF-c4jks5qRnESgaJpZM4JDbZ-
.

@GuillaumeGomez
Copy link
Member

Really? That complicates things a bit. We should then create a glossary for keywords.

@GuillaumeGomez
Copy link
Member

And while I think about it: cc @steveklabnik

@steveklabnik steveklabnik added T-tools A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools labels Mar 9, 2017
@steveklabnik steveklabnik added T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. and removed T-tools labels May 18, 2017
@Mark-Simulacrum Mark-Simulacrum added the C-enhancement Category: An issue proposing an enhancement or a PR with one. label Jul 25, 2017
@steveklabnik steveklabnik added the P-medium Medium priority label Aug 30, 2017
@GuillaumeGomez
Copy link
Member

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

@GuillaumeGomez GuillaumeGomez self-assigned this May 23, 2018
@QuietMisdreavus
Copy link
Member

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 #[doc(keyword="match")] for these. It would require making a new kind of page for them, but if we base it on the primitive pages (without all the method/trait implementations) it shouldn't be that bad. Writing all the docs, on the other hand, will require some footwork.

@GuillaumeGomez
Copy link
Member

I'll work on adding the keyword pages first then. For the documentation, I may be not the best to write it.

@ollie27
Copy link
Member

ollie27 commented Jun 2, 2018

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 std API, the books, the reference, the error index, etc... Then we could add a new book to cover all the keywords assuming they're not documented sufficiently elsewhere.

bors added a commit that referenced this issue Jun 5, 2018
rustdoc: introduce the #[doc(keyword="")] attribute for documenting keywords

Part of #34601.

r? @QuietMisdreavus
kennytm added a commit to kennytm/rust that referenced this issue Aug 12, 2018
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Aug 12, 2018
…Misdreavus

Add let keyword doc

Part of rust-lang#34601.

r? @rust-lang/docs
@DevQps
Copy link
Contributor

DevQps commented Apr 2, 2019

@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 (let, struct and enum have documentation for example).

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:

  • break
  • use
  • dyn
  • else
  • in
  • match
  • mod
  • move
  • mut
  • pub
  • ref
  • return
  • self
  • static
  • super
  • trait
  • type
  • unsafe
  • while
  • where

Reserved for Future Use:

  • abstract
  • async
  • become
  • box
  • do
  • final
  • macro
  • override
  • priv
  • try
  • typeof
  • unsized
  • virtual
  • yield

Personally I wonder if keywords like else, break and while need some documentation since they are so basic to almost all programming languages. But I'll leave that up to you guys. I do however think that it would be better to create a new issue with a checklist and close this one, since it felt like the whole discussion here was about "how" we were going realize searching for keywords in the docs, instead of actually doing it.

@ollie27
Copy link
Member

ollie27 commented Apr 2, 2019

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 std docs was a good idea but I guess that ship has already sailed. Maybe we can turn them into a separate keyword book at some point instead though.

@DevQps
Copy link
Contributor

DevQps commented Apr 2, 2019

@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.

Manishearth added a commit to Manishearth/rust that referenced this issue Jun 30, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 30, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 30, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 30, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 30, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 30, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 1, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 1, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 1, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 1, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 1, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 1, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 13, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 13, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 13, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 13, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 14, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 14, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 14, 2020
…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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 18, 2020
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
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 19, 2020
Documentation for the false keyword

Partial fix of rust-lang#34601.

Short documentation for the false keyword mainly pointing to the `true` keyword.
Manishearth added a commit to Manishearth/rust that referenced this issue Jul 20, 2020
Documentation for the false keyword

Partial fix of rust-lang#34601.

Short documentation for the false keyword mainly pointing to the `true` keyword.
bors added a commit to rust-lang-ci/rust that referenced this issue Jul 24, 2020
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.
bors added a commit to rust-lang-ci/rust that referenced this issue Jul 25, 2020
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
@poliorcetics
Copy link
Contributor

The last PR for this is #73943 (unsafe keyword), after that it will be done !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. P-medium Medium priority T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.