Add stubs to keyword docs #60817
Merged
Add stubs to keyword docs #60817
Conversation
This file contains 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
|
r? @shepmaster (rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
ecstatic-morse
force-pushed
the
issue-60779
branch
from
5603c20
to
e4b0579
Compare
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
|
/cc @rust-lang/docs |
shepmaster
added
the
A-docs
CryZe
reviewed
May 14, 2019
|
I have general unease over the amount of duplication between this content, TRPL, and the reference. |
|
My point in #60779 is that if the main documentation page has a keyword list, then the list should be correct (perhaps with stubs). Whether placing the keyword docs on that page is a good idea or not is a separate question. |
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
ecstatic-morse
force-pushed
the
issue-60779
branch
from
6ef4d5f
to
ef56ff5
Compare
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
Centril
reviewed
May 14, 2019
Centril
reviewed
May 14, 2019
|
It would be good to add a paragraph explicitly saying that the doc is not yet written and inviting the reader to make a PR for the keywords with missing documentation body. |
|
@petrochenkov These summary lines are visible on
The last one seemed least bad. |
It's not even less bad, it's certainly better in the long run! |
|
@petrochenkov Will do. How about: "The documentation for this keyword is not yet complete. Pull requests welcome!" |
|
Seems good to me. |
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
Centril
reviewed
May 15, 2019
|
Btw, when you're done with changes altogether, can you squash things into a single commit? (also please avoid @-mentioning folks in commits cause it generates many emails ^^). |
ecstatic-morse
force-pushed
the
issue-60779
branch
2 times, most recently
from
0161fb7
to
7c4f161
Compare
|
I added Note that there's still some reserved or nightly only keywords that don't appear on this list ( |
Centril
reviewed
May 15, 2019
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
ecstatic-morse
force-pushed
the
issue-60779
branch
from
7c4f161
to
21e6144
Compare
|
I fixed the broken doc link and noted that |
This commit gives each stable keyword a short entry in the "Keywords"
section in the docs for `std`. The newly added entries are a single
summary line and a note that the documentation is not yet complete. I
changed some of the existing summary lines for consistency's sake. Each
line is either a verb phrase ("name the type of a trait object" for
`dyn`), or an object ("A value of type `bool` representing logical true"
for `true`). I tried to avoid using the keyword itself or the word
"keyword" in the summary.
Later PRs can flesh out each keyword with an example of each
context in which a keyword can appear and a link to the rust book.
Keywords which are not close to stable rust such as `box` (which is
getting unstabilized) or `try` are ignored in this PR.
ecstatic-morse
force-pushed
the
issue-60779
branch
from
21e6144
to
851be33
Compare
|
r=me with green travis :) |
|
@bors r+ rollup |
|
📌 Commit 851be33 has been approved by |
bors
added
S-waiting-on-bors
bors
added a commit
that referenced
this pull request
May 17, 2019
Add stubs to keyword docs Resolves #60779. This commit gives each stable keyword a short entry in the "Keywords" section in the docs for `std`. The newly added entries are only a single line each and contain the main purpose of the keyword. I changed some of the existing summary lines for consistency's sake. Each line is either an imperative ("name the type of a trait object" for `dyn`), or an object ("An abstract data type" for `enum`). I tried to avoid using the keyword itself or the word "keyword" in the summary. Later commits can flesh out each keyword with an example for each context in which it can appear as well as a link to the appropriate part of the rust book. **edit:** Here's the list of keywords and summaries (sans formatting) to ease reviewing. I'll try to keep this up to date as I make changes: keyword | summary -- | -- Self | The implementing type within a `trait` or `impl` block, or the current type within a type definition. as | Cast between types, or rename an import. async | ExperimentalReturn a Future instead of blocking the current thread. await | ExperimentalSuspend execution until the result of a Future is ready. break | Exit early from a loop. const | Compile-time constants and deterministic functions. continue | Skip to the next iteration of a loop. crate | A Rust binary or library. dyn | Name the type of a trait object. else | What to do when an if condition does not hold. enum | A type that can be any one of several variants. extern | Link to or import external code. false | A value of type bool representing logical false. fn | A function or function pointer. for | Iteration with in, trait implementation with impl, or higher-ranked trait bounds (for<'a>). if | Evaluate a block if a condition holds. impl | Implement some functionality for a type. in | Iterate over a series of values with for. let | Bind a value to a variable. loop | Loop indefinitely. match | Control flow based on pattern matching. mod | Organize code into modules. move | Capture a closure's environment by value. mut | A mutable binding, reference, or pointer. pub | Make an item visible to others. ref | Bind by reference during pattern matching. return | Return a value from a function. self | The receiver of a method, or the current module. static | A place that is valid for the duration of a program. struct | A type that is composed of other types. super | The parent of the current module. trait | A common interface for a class of types. true | A value of type bool representing logical true. type | Define an alias for an existing type. union | The Rust equivalent of a C-style union. unsafe | Code or interfaces whose memory safety cannot be verified by the type system. use | Import or rename items from other crates or modules. where | Add constraints that must be upheld to use an item. while | Loop while a condition is upheld.
|
☀️ Test successful - checks-travis, status-appveyor |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Resolves #60779.
This commit gives each stable keyword a short entry in the "Keywords" section in the docs for
std. The newly added entries are only a single line each and contain the main purpose of the keyword. I changed some of the existing summary lines for consistency's sake. Each line is either an imperative ("name the type of a trait object" fordyn), or an object ("An abstract data type" forenum). I tried to avoid using the keyword itself or the word "keyword" in the summary.Later commits can flesh out each keyword with an example for each context in which it can appear as well as a link to the appropriate part of the rust book.
edit:
Here's the list of keywords and summaries (sans formatting) to ease reviewing. I'll try to keep this up to date as I make changes:
traitorimplblock, or the current type within a type definition.