-
Notifications
You must be signed in to change notification settings - Fork 12.9k
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
Gradually expanding libstd's keyword documentation #53931
Conversation
The whole keyword docs thing is pretty new in Rust's history and needs some work before it's a shining gem. Here's hoping I can provide that. I basically shoved in a bunch of the most important information from the reference and the book, along with leaving links to both at the end. I don't think keyword docs need to have complete detail, just all the broad strokes, so if someone's confused about a usage of a keyword they can look at the std documentation for that keyword.
It's pretty basic and could do with more details, but it's a good starter until someone else improves it.
Turns out writing docs on keywords that are used in multiple different places in entirely different contexts gets a little harder. I put a footnote on `*const` syntax just to make sure you can find it if need be, but it might need more detail.
r? @cramertj (rust_highfive has picked a reviewer for you, use r? to override) |
src/libstd/keyword_docs.rs
Outdated
/// [book]: https://doc.rust-lang.org/book/second-edition/ch05-01-defining-structs.html | ||
/// [reference]: https://doc.rust-lang.org/reference/items/structs.html | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No need for this line.
cc #51451 r? @rust-lang/docs |
src/libstd/keyword_docs.rs
Outdated
/// Empty structs are instantiated with just their name and nothing else. `let thing = | ||
/// EmptyStruct;` | ||
/// | ||
/// |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Extra empty line.
src/libstd/keyword_docs.rs
Outdated
/// Tuple structs are instantiated in the same way as tuples themselves, except with the struct's | ||
/// name as a prefix: `Foo(123, false, 0.1)`. | ||
/// | ||
/// Empty structs are instantiated with just their name and nothing else. `let thing = |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Weird wording and punctuation.
I didn't read everything yet. Just thinking: is it useful/a good idea to add a few documentation in here which is already available in the book? I'm not against it, I think it's great, just wondering what others might think about it. cc @rust-lang/docs |
Mostly addressing notes on ambiguous syntax and spurious newlines.
This comment has been minimized.
This comment has been minimized.
That travis error looks like a bug in tidy. I thought it was supposed to ignore lines that looked like markdown links? |
I think it might be used in some other things, but I'm not fluent enough at sifting through the rust compiler's source code to find every use of a specific keyword. This leaves the question of how to document the `extern` keyword, what with how much overlap it has with `crate`, but that's used with ABI stuff so that should be fine.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
src/libstd/keyword_docs.rs
Outdated
@@ -8,25 +8,361 @@ | |||
// option. This file may not be copied, modified, or distributed | |||
// except according to those terms. | |||
|
|||
#[doc(keyword = "as")] | |||
// | |||
/// The type coercion keyword. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we call this "casting" instead of coercion -- see https://doc.rust-lang.org/book/second-edition/appendix-01-keywords.html.
src/libstd/keyword_docs.rs
Outdated
/// assert_eq!(true as u8 + thing2 as u8, 100); | ||
/// ``` | ||
/// | ||
/// In general, any coercion that can be performed via writing out type hints can also be done |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"via type hints" -> "by ascribing the type"
src/libstd/keyword_docs.rs
Outdated
/// assert_eq!(true as u8 + thing2 as u8, 100); | ||
/// ``` | ||
/// | ||
/// In general, any coercion that can be performed via writing out type hints can also be done |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
coercion -> cast
src/libstd/keyword_docs.rs
Outdated
/// | ||
/// In general, any coercion that can be performed via writing out type hints can also be done | ||
/// using `as`, so instead of writing `let x: u32 = 123`, you can write `let x = 123 as u32` (Note: | ||
/// `let x = 123u32` would be best in that situation). The same is not true in the other direction, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That let x = 123u32
would be best is probably disputed; I would prefer let x: u32 = 123;
myself, or when we get type ascription, let x = 123: u32;
.
However, explicit casting with as
where implicit coercions apply should be discouraged here.
src/libstd/keyword_docs.rs
Outdated
/// | ||
/// Constants must be explicitly typed, unlike with `let` you can't ignore its type and let the | ||
/// compiler figure it out. Any constant value can be defined in a const, which in practice happens | ||
/// to be most things that would be reasonable to have a constant. For example, you can't have a |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"which in practice happens to be most things that would be reasonable to have a constant".. this is either not true or too vague to be useful. There are many things which could be const
in the future which currently aren't due to the lack of stable const fn
(but this is coming soon..)
src/libstd/keyword_docs.rs
Outdated
/// | ||
/// struct Empty; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Empty -> Unit
src/libstd/keyword_docs.rs
Outdated
/// etc, starting at zero. | ||
/// | ||
/// Empty structs, or unit-like structs, are most commonly used as markers, for example | ||
/// [`PhantomData`]. Empty structs have a size of zero bytes, but unlike empty enums they can be |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PhantomData
is very special here; so it's not a particularly good example.
src/libstd/keyword_docs.rs
Outdated
/// | ||
/// Empty structs, or unit-like structs, are most commonly used as markers, for example | ||
/// [`PhantomData`]. Empty structs have a size of zero bytes, but unlike empty enums they can be | ||
/// instantiated, making them similar to the unit type `()`. Unit-like structs are useful when you |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
similar -> isomorphic
src/libstd/keyword_docs.rs
Outdated
/// | ||
/// # Instantiation | ||
/// | ||
/// Structs can be instantiated in a manner of different ways, each of which can be mixed and |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"in a manner of different ways" -> "in different ways"
Thank you to @Centril for the valuable critique provided. At this rate, the rest of the major keywords should be finished in under a month, and I'll keep working away at it until then. |
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 |
src/libstd/keyword_docs.rs
Outdated
@@ -10,7 +10,7 @@ | |||
|
|||
#[doc(keyword = "as")] | |||
// | |||
/// The type coercion keyword. | |||
/// The keyword for casting types. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would reword this slightly to: "The keyword for casting a value to a type."
src/libstd/keyword_docs.rs
Outdated
@@ -130,8 +134,8 @@ mod crate_keyword { } | |||
/// | |||
/// Enums in Rust are similar to those of other compiled languages like C, but have important | |||
/// differences that make them considerably more powerful. What Rust calls enums are more commonly | |||
/// known as Algebraic Data Types if you're coming from a functional programming background, but | |||
/// the important part is that data can go with the enum variants. | |||
/// known as Algebraic Data Types if you're coming from a functional programming background. The |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Continuing on... I would simply make "Algebraic Data Types" a link pointing to https://en.wikipedia.org/wiki/Algebraic_data_type. E.g. Algebraic Data Types.
While most people can find that by using google, effective documentation should provide such material directly instead of having the user go through indirections. The wiki page also has useful links that can give users more in-depth explanations in perhaps more familiar syntax.
for some reason homu missed this PR |
⌛ Testing commit 619dfeb with merge 83873ed9c9f7a97d14b43dafe8e6a79e463c3188... |
💔 Test failed - status-appveyor |
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 |
1 similar comment
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 |
Ugh, I don't know how to fix the new errors. Can someone help me out? |
src/libstd/keyword_docs.rs
Outdated
/// The mirror use case of FFI is also done via the `extern` keyword: | ||
/// | ||
/// ```rust | ||
/// # #![allow(private_no_mangle_fns)] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Try and remove this line; this is what the error references I think.
This was added in the fortnight this PR spent stale. I'm hoping this one-liner fixes it.
@bors r=steveklabnik |
@gankro: 🔑 Insufficient privileges: Not in reviewers |
@bors r=steveklabnik |
@Centril: 🔑 Insufficient privileges: Not in reviewers |
Sigh; I need to get |
@bors r=steveklabnik |
📌 Commit 320ec81 has been approved by |
Gradually expanding libstd's keyword documentation I'm working on adding new keywords to the documentation and refreshing the incomplete older ones, and I'm hoping that I can eventually add all the standalone-usable keywords after a bunch of incremental work. It would be cool to see the keywords section of std's docs be a definitive reference as to what each keyword means when you see it, and that's what I'm aiming towards with this work. I'm far from a Rust expert so there will inevitably be things to fix in this, also I'm not sure if this should be a bunch of quickly-merged PRs or one gradually-updated PR that gets merged once it's done.
Gradually expanding libstd's keyword documentation I'm working on adding new keywords to the documentation and refreshing the incomplete older ones, and I'm hoping that I can eventually add all the standalone-usable keywords after a bunch of incremental work. It would be cool to see the keywords section of std's docs be a definitive reference as to what each keyword means when you see it, and that's what I'm aiming towards with this work. I'm far from a Rust expert so there will inevitably be things to fix in this, also I'm not sure if this should be a bunch of quickly-merged PRs or one gradually-updated PR that gets merged once it's done.
Rollup of 22 pull requests Successful merges: - #53507 (Add doc for impl From for Waker) - #53931 (Gradually expanding libstd's keyword documentation) - #54965 (update tcp stream documentation) - #54977 (Accept `Option<Box<$t:ty>>` in macro argument) - #55138 (in which unused-parens suggestions heed what the user actually wrote) - #55173 (Suggest appropriate syntax on missing lifetime specifier in return type) - #55200 (Documents `From` implementations for `Stdio`) - #55245 (submodules: update clippy from 5afdf8b to b1d0343) - #55247 (Clarified code example in char primitive doc) - #55251 (Fix a typo in the documentation of RangeInclusive) - #55253 (only issue "variant of the expected type" suggestion for enums) - #55254 (Correct trailing ellipsis in name_from_pat) - #55269 (fix typos in various places) - #55282 (Remove redundant clone) - #55285 (Do some copy editing on the release notes) - #55291 (Update stdsimd submodule) - #55296 (Set RUST_BACKTRACE=0 for rustdoc-ui/failed-doctest-output.rs) - #55306 (Regression test for #54478.) - #55328 (Fix doc for new copysign functions) - #55340 (Operands no longer appear in places) - #55345 (Remove is_null) - #55348 (Update RELEASES.md after destabilization of non_modrs_mods) Failed merges: r? @ghost
I'm working on adding new keywords to the documentation and refreshing the incomplete older ones, and I'm hoping that I can eventually add all the standalone-usable keywords after a bunch of incremental work. It would be cool to see the keywords section of std's docs be a definitive reference as to what each keyword means when you see it, and that's what I'm aiming towards with this work.
I'm far from a Rust expert so there will inevitably be things to fix in this, also I'm not sure if this should be a bunch of quickly-merged PRs or one gradually-updated PR that gets merged once it's done.