Std module docs improvements by camsteffen · Pull Request #93162 · rust-lang/rust

camsteffen · 2022-01-21T15:46:07Z

My primary goal is to create a cleaner separation between primitive types and primitive type helper modules (fixes#92777). I also changed a few header lines in other top-level std modules (seen at https://doc.rust-lang.org/std/) for consistency.

Some conventions used/established:

"The `Box<T>` type for heap allocation." - if a module mainly provides a single type, name it and summarize its purpose in the module header
"Utilities for the _ primitive type." - this wording is used for the header of helper modules
Documentation for primitive types themselves are removed from helper modules
provided-by-core functionality of primitive types is documented in the primitive type instead of the helper module (such as the "Iteration" section in the slice docs)

I wonder if some content in std::ptr should be in pointer but I did not address this.

rust-highfive · 2022-01-21T15:46:10Z

r? @m-ou-se

(rust-highfive has picked a reviewer for you, use r? to override)

m-ou-se · 2022-01-22T18:47:21Z

It makes me super happy to see someone working on documentation consistency. I'll try to make the time to review this soon.

m-ou-se

This is great. Thanks for doing this.

I have a few small comments, but all of them are basically comments about the old documentation that you moved, so not really comments on your changes. If you feel like addressing them, go ahead. But r=me either way. :)

m-ou-se · 2022-02-07T11:08:09Z

While every string literal is a string slice, not every string slice is a literal, so let's avoid implying they are the same thing. (A 'string slice' could also refer to (a part of) a String, for example.)

Suggested change
/// Here we have declared a string literal, also known as a string slice.
/// Here we have declared a string slice initialized with a string literal.

m-ou-se · 2022-02-07T11:11:12Z

I'd be careful with using the term 'unicode string'. That's used in some other languages/on other platforms to refer to [u32] or [u16] string representations. You could mention UTF-8 specifically, but that's already mentioned below and might be a bit too much detail for the first line.

I could just undo this change. Also is "slices" a bit over-technical or confusing? I'm not how sure "slice" applies to a const &'static str for example. How about "The primitive string type"?

"Slices" might be important to not cause confusion with the String type.
I'm not how sure "slice" applies to a const &'static str for example.
That's still a pointer+size to a 'slice' of the program (where the string is stored). But I suppose the main point is that if you take any substring, you still have the same type.

I'll just revert this.

m-ou-se · 2022-02-07T11:14:49Z

This module also provides TypeId and type_name. While related to Any, they're also useful without directly using that trait.
Not entirely sure how to summarize these together in one line though. Something about type erasure or dynamic typing or reflection maybe?

How about
Utilities for dynamic typing or working with any type.
supposing Any and TypeId falls under "dynamic typing" and type_name is a util that works with any type.

Yeah that could work. Or maybe "Utilities related to type erasure."? Either way is fine, as long as it doesn't imply it's only the Any type.

Currently landed on "Utilities for dynamic typing or type reflection." I feel that "erasure" is a sub-concept of "dynamic typing", and TypeId and type_name are both utilities for "reflection", so that word is good to include.

m-ou-se · 2022-02-07T11:30:10Z

Both of these examples work with and without [..], but only the mut version uses that now. The first one now iterates over a reference to an array, not over the (unsized) slice.
Maybe these should coerce the type explicitly to a slice, and then iterate over that without any [..]?
Suggested change
/// ```
/// let numbers = &[0, 1, 2];
/// for n in numbers {
/// println!("{} is a number!", n);
/// }
/// ```
///
/// The mutable slice yields mutable references to the elements:
///
/// ```
/// let mut scores = [7, 8, 9];
/// for score in &mut scores[..] {
/// *score += 1;
/// }
/// ```
/// ```
/// let numbers: &[i32] = &[0, 1, 2];
/// for n in numbers {
/// println!("{} is a number!", n);
/// }
/// ```
///
/// The mutable slice yields mutable references to the elements:
///
/// ```
/// let scores: &mut [i32] = &mut [7, 8, 9];
/// for score in scores {
/// *score += 1;
/// }
/// ```

JohnCSimon · 2022-03-06T04:14:31Z

ping from triage:
@camsteffen
can you address the comments from m-ou-se?

FYI: when a PR is ready for review, post a message containing
@rustbot ready to switch the PR to S-waiting-on-review so the PR appears in the reviewer's backlog.

camsteffen · 2022-03-06T14:41:25Z

My bad. Waiting for feedback.

@rustbot ready

bors · 2022-03-11T02:09:31Z

☔ The latest upstream changes (presumably #94824) made this pull request unmergeable. Please resolve the merge conflicts.

camsteffen · 2022-04-30T17:07:05Z

@rustbot ready

Rebased and addressed comments.

camsteffen · 2022-04-30T17:21:00Z

Threw in a fix for variable capturing in tidy_error!.

bors · 2022-05-26T22:10:15Z

☔ The latest upstream changes (presumably #97434) made this pull request unmergeable. Please resolve the merge conflicts.

camsteffen · 2022-05-27T00:10:37Z

Rebased. I'm not sure if I'm conflicting with the intent of #96033 which seems to make std::error into a page about general error handling best practices.

bors · 2022-06-10T04:09:07Z

☔ The latest upstream changes (presumably #91970) made this pull request unmergeable. Please resolve the merge conflicts.

JohnCSimon · 2022-07-03T04:18:03Z

ping from triage:
@camsteffen this has a merge conflict

camsteffen · 2022-07-03T19:41:33Z

Rebased. I decided to bulldoze the header line added to core::any in #91970 in order to keep it short.

camsteffen · 2022-08-20T18:22:30Z

Addressed @Mark-Simulacrum's comments.

@rustbot ready

Mark-Simulacrum · 2022-08-20T20:42:54Z

r=me with commits squashed and the unrelated tidy change dropped.

camsteffen · 2022-08-20T21:53:47Z

@bors r=Mark-Simulacrum

bors · 2022-08-20T21:53:48Z

📌 Commit 17ddcb4 has been approved by Mark-Simulacrum

It is now in the queue for this repository.

Rollup of 5 pull requests Successful merges: - rust-lang#93162 (Std module docs improvements) - rust-lang#99386 (Add tests that check `Vec::retain` predicate execution order.) - rust-lang#99915 (Recover keywords in trait bounds) - rust-lang#100694 (Migrate rustc_ast_passes diagnostics to `SessionDiagnostic` and translatable messages (first part)) - rust-lang#100757 (Catch overflow early) Failed merges: - rust-lang#99917 (Move Error trait into core) r? `@ghost` `@rustbot` modify labels: rollup

yaahc · 2022-08-22T20:20:03Z

Rebased. I'm not sure if I'm conflicting with the intent of #96033 which seems to make std::error into a page about general error handling best practices.

Looks like the answer is yes 😅, I'm going to go ahead and revert the change you made to the module description since I intend to have more than just the Error trait in the std::error module, such as Chain and Report types.

rust-highfive assigned m-ou-se Jan 21, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 21, 2022

m-ou-se added the T-libs Relevant to the library team, which will review and decide on the PR/issue. label Jan 22, 2022

m-ou-se approved these changes Feb 7, 2022
View reviewed changes

m-ou-se added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 7, 2022

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 6, 2022

m-ou-se added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 9, 2022

camsteffen force-pushed the std-prim-docs branch from 84bec7d to fb046bfCompare April 30, 2022 17:05

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Apr 30, 2022

camsteffen force-pushed the std-prim-docs branch from fb046bf to 796af21Compare April 30, 2022 17:18

camsteffen force-pushed the std-prim-docs branch from 796af21 to 773fc3bCompare May 27, 2022 00:08

camsteffen requested a review from m-ou-se May 27, 2022 00:11

camsteffen force-pushed the std-prim-docs branch from 773fc3b to 1854b43Compare July 3, 2022 19:39

This comment was marked as resolved.
Sign in to view

Mark-Simulacrum reviewed Jul 31, 2022
View reviewed changes

Comment threadlibrary/alloc/src/slice.rs Outdated
Comment threadlibrary/core/src/primitive_docs.rs Outdated
Comment threadlibrary/core/src/primitive_docs.rs Outdated

Mark-Simulacrum assigned Mark-Simulacrum and unassigned m-ou-se Jul 31, 2022

Mark-Simulacrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 31, 2022

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 20, 2022

Mark-Simulacrum reviewed Aug 20, 2022
View reviewed changes

Comment threadsrc/tools/tidy/src/lib.rs Outdated

Improve primitive/std docs separation and headers
17ddcb4

camsteffen force-pushed the std-prim-docs branch from 39c3bea to 17ddcb4Compare August 20, 2022 21:52

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 20, 2022

Dylan-DPC mentioned this pull request Aug 22, 2022
Rollup of 5 pull requests #100868
Merged

bors merged commit a4950ef into rust-lang:masterAug 22, 2022

rustbot added this to the 1.65.0 milestone Aug 22, 2022

camsteffen deleted the std-prim-docs branch August 22, 2022 22:52

	/// Here we have declared a string literal, also known as a string slice.
	/// Here we have declared a string slice initialized with a string literal.

-/// ```
-/// let numbers = &[0, 1, 2];
-/// for n in numbers {
-/// println!("{} is a number!", n);
-/// }
-/// ```
-///
-/// The mutable slice yields mutable references to the elements:
-///
-/// ```
-/// let mut scores = [7, 8, 9];
-/// for score in &mut scores[..] {
-/// *score += 1;
-/// }
-/// ```
+/// ```
+/// let numbers: &[i32] = &[0, 1, 2];
+/// for n in numbers {
+/// println!("{} is a number!", n);
+/// }
+/// ```
+///
+/// The mutable slice yields mutable references to the elements:
+///
+/// ```
+/// let scores: &mut [i32] = &mut [7, 8, 9];
+/// for score in scores {
+/// *score += 1;
+/// }
+/// ```

Uh oh!

Uh oh!

Conversation

camsteffen commented Jan 21, 2022

Uh oh!

rust-highfive commented Jan 21, 2022

Uh oh!

m-ou-se commented Jan 22, 2022

Uh oh!

m-ou-se left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JohnCSimon commented Mar 6, 2022

Uh oh!

camsteffen commented Mar 6, 2022

Uh oh!

bors commented Mar 11, 2022

Uh oh!

camsteffen commented Apr 30, 2022

Uh oh!

camsteffen commented Apr 30, 2022

Uh oh!

bors commented May 26, 2022

Uh oh!

camsteffen commented May 27, 2022• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bors commented Jun 10, 2022

Uh oh!

JohnCSimon commented Jul 3, 2022

Uh oh!

This comment was marked as resolved.

camsteffen commented Jul 3, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

camsteffen commented Aug 20, 2022

Uh oh!

Uh oh!

Mark-Simulacrum commented Aug 20, 2022

Uh oh!

camsteffen commented Aug 20, 2022

Uh oh!

bors commented Aug 20, 2022

Uh oh!

yaahc commented Aug 22, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

camsteffen commented May 27, 2022•
edited
Loading