Std module docs improvements #93162

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

library/core/src/primitive_docs.rs

 /// ```
 ///
-/// They are `'static` because they're stored directly in the final binary, and
-/// so will be valid for the `'static` duration.
+/// Here we have declared a string literal, also known as a string slice.


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

library/core/src/primitive_docs.rs

 #[stable(feature = "rust1", since = "1.0.0")]
 mod prim_slice {}

 #[doc(primitive = "str")]
 //
-/// String slices.
+/// Unicode string slices.


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

library/core/src/any.rs

+//! The `Any` trait enables dynamic typing of any `'static` type through runtime
+//! reflection.


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

library/core/src/primitive_docs.rs

+/// ```
+/// 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;
+/// }
+/// ```


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.

library/alloc/src/slice.rs

library/core/src/primitive_docs.rs

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

Addressed @Mark-Simulacrum's comments.

@rustbot ready

src/tools/tidy/src/lib.rs

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 fb046bf Compare 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 796af21 Compare April 30, 2022 17:18

camsteffen force-pushed the std-prim-docs branch from 796af21 to 773fc3b Compare 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 1854b43 Compare July 3, 2022 19:39

This comment was marked as resolved.

Sign in to view

Mark-Simulacrum reviewed Jul 31, 2022

View reviewed changes

library/alloc/src/slice.rs Outdated Show resolved Hide resolved

library/core/src/primitive_docs.rs Outdated Show resolved Hide resolved

library/core/src/primitive_docs.rs Outdated Show resolved Hide resolved

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

src/tools/tidy/src/lib.rs Outdated Show resolved Hide resolved

Improve primitive/std docs separation and headers

17ddcb4

camsteffen force-pushed the std-prim-docs branch from 39c3bea to 17ddcb4 Compare 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:master Aug 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Std module docs improvements #93162

Std module docs improvements #93162

camsteffen commented Jan 21, 2022

rust-highfive commented Jan 21, 2022

m-ou-se commented Jan 22, 2022

m-ou-se left a comment

m-ou-se Feb 7, 2022

camsteffen Mar 29, 2022

m-ou-se Feb 7, 2022

camsteffen Feb 9, 2022

m-ou-se Mar 9, 2022

camsteffen Mar 29, 2022

m-ou-se Feb 7, 2022

camsteffen Feb 9, 2022

m-ou-se Mar 9, 2022

camsteffen Apr 30, 2022

m-ou-se Feb 7, 2022

JohnCSimon commented Mar 6, 2022

camsteffen commented Mar 6, 2022

bors commented Mar 11, 2022

camsteffen commented Apr 30, 2022

camsteffen commented Apr 30, 2022

bors commented May 26, 2022

camsteffen commented May 27, 2022 •

edited

Loading

bors commented Jun 10, 2022

JohnCSimon commented Jul 3, 2022

This comment was marked as resolved.

camsteffen commented Jul 3, 2022

camsteffen commented Aug 20, 2022

Mark-Simulacrum commented Aug 20, 2022

camsteffen commented Aug 20, 2022

bors commented Aug 20, 2022

yaahc commented Aug 22, 2022

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

		//! The `Any` trait enables dynamic typing of any `'static` type through runtime
		//! reflection.

Std module docs improvements #93162

Std module docs improvements #93162

Conversation

camsteffen commented Jan 21, 2022

rust-highfive commented Jan 21, 2022

m-ou-se commented Jan 22, 2022

m-ou-se left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JohnCSimon commented Mar 6, 2022

camsteffen commented Mar 6, 2022

bors commented Mar 11, 2022

camsteffen commented Apr 30, 2022

camsteffen commented Apr 30, 2022

bors commented May 26, 2022

camsteffen commented May 27, 2022 • edited Loading

bors commented Jun 10, 2022

JohnCSimon commented Jul 3, 2022

This comment was marked as resolved.

camsteffen commented Jul 3, 2022

camsteffen commented Aug 20, 2022

Mark-Simulacrum commented Aug 20, 2022

camsteffen commented Aug 20, 2022

bors commented Aug 20, 2022

yaahc commented Aug 22, 2022

camsteffen commented May 27, 2022 •

edited

Loading