Use consistent punctuation for 'Prelude contents' docs #80172

camelid · 2020-12-18T23:01:25Z

No description provided.

rust-highfive · 2020-12-18T23:01:29Z

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

camelid · 2020-12-18T23:08:04Z

library/std/src/prelude/mod.rs

+//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`], [`Unpin`]}:
+//!   Marker traits that indicate fundamental properties of types.
+//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}: Various
 //!   operations for both destructors and overloading `()`.
-//! * [`std::mem`]::[`drop`][`mem::drop`], a convenience function for explicitly
+//! * [`std::mem`]::[`drop`][`mem::drop`]: A convenience function for explicitly
 //!   dropping a value.
-//! * [`std::boxed`]::[`Box`], a way to allocate values on the heap.
-//! * [`std::borrow`]::[`ToOwned`], the conversion trait that defines
+//! * [`std::boxed`]::[`Box`]: A way to allocate values on the heap.
+//! * [`std::borrow`]::[`ToOwned`]: The conversion trait that defines
 //!   [`to_owned`], the generic method for creating an owned type from a
 //!   borrowed type.
-//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines
+//! * [`std::clone`]::[`Clone`]: The ubiquitous trait that defines
 //!   [`clone`][`Clone::clone`], the method for producing a copy of a value.
-//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }, the
+//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`]}: The
 //!   comparison traits, which implement the comparison operators and are often
 //!   seen in trait bounds.
-//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}, generic
+//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}: Generic
 //!   conversions, used by savvy API authors to create overloaded methods.
 //! * [`std::default`]::[`Default`], types that have default values.
-//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`]
-//!   [`DoubleEndedIterator`], [`ExactSizeIterator`]}, iterators of various
+//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`],
+//!   [`DoubleEndedIterator`], [`ExactSizeIterator`]}: Iterators of various
 //!   kinds.
 //! * [`std::option`]::[`Option`]::{[`self`][`Option`], [`Some`], [`None`]}, a
 //!   type which expresses the presence or absence of a value. This type is so
 //!   commonly used, its variants are also exported.
-//! * [`std::result`]::[`Result`]::{[`self`][`Result`], [`Ok`], [`Err`]}, a type
+//! * [`std::result`]::[`Result`]::{[`self`][`Result`], [`Ok`], [`Err`]}: A type
 //!   for functions that may succeed or fail. Like [`Option`], its variants are
 //!   exported as well.
-//! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings.
-//! * [`std::vec`]::[`Vec`], a growable, heap-allocated vector.
+//! * [`std::string`]::{[`String`], [`ToString`]}: Heap-allocated strings.
+//! * [`std::vec`]::[`Vec`]: A growable, heap-allocated vector.


It might be better in lowercase, but either way I think it should be consistent among all of these items.

it is better in lowercase, yes. I do like the : better than the , though, and being consistent is good.

camelid · 2020-12-18T23:08:18Z

r? @steveklabnik maybe?

steveklabnik

Thanks for this! A few comments/questions.

steveklabnik · 2020-12-28T16:52:35Z

library/std/src/io/prelude.rs

@@ -1,4 +1,4 @@
-//! The I/O Prelude
+//! # The I/O Prelude


Why is this change being made?

Because it's basically the title of the page, so it looks better (IMHO) as a heading. The way it is now looks kind of funny:

It's also consistent with the docs at the std root, which use # The Rust Standard Library. Though if we make this change, we should probably also make std::prelude's title a heading (currently it's not).

Yes so, I would rather change this in Rustdoc than make every single heading have a #. The convention is generally to not include this, and so by doing it on one or two pages, it's gonna be weird for those and not all other code in existence.

Yes so, I would rather change this in Rustdoc than make every single heading have a #.

I'm not sure what you mean by "change this in Rustdoc". Can you explain a bit?

The convention is generally to not include this, and so by doing it on one or two pages, it's gonna be weird for those and not all other code in existence.

Other pages seem to usually use lowercase text with a period at the end. (E.g., std::alloc.) Maybe it would be best to change this to use that style?

I feel like perhaps std::prelude should use a heading though, to be consistent with # The Rust Standard Library and # The Rust Core Library.

I'm not sure what you mean by "change this in Rustdoc". Can you explain a bit?

If you want the summary line to be larger, I would change Rustdoc to produce this output, rather than changing the contents of the doc string.

Other pages seem to usually use lowercase text with a period at the end.

Yep, that seems good to me, see https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#summary-sentence

to be consistent with # The Rust Standard Library and # The Rust Core Library.

Arguably those are inconsistent with the rest of the docs.

If you want the summary line to be larger, I would change Rustdoc to produce this output, rather than changing the contents of the doc string.

I don't want the summary line to be larger; I'm not sure what I said that made you think that :)

Also, changing it to be a heading shouldn't change the contents of the summary line at all.

steveklabnik · 2020-12-28T16:53:13Z

library/std/src/prelude/mod.rs

+//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`], [`Unpin`]}:
+//!   Marker traits that indicate fundamental properties of types.
+//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}: Various
 //!   operations for both destructors and overloading `()`.
-//! * [`std::mem`]::[`drop`][`mem::drop`], a convenience function for explicitly
+//! * [`std::mem`]::[`drop`][`mem::drop`]: A convenience function for explicitly
 //!   dropping a value.
-//! * [`std::boxed`]::[`Box`], a way to allocate values on the heap.
-//! * [`std::borrow`]::[`ToOwned`], the conversion trait that defines
+//! * [`std::boxed`]::[`Box`]: A way to allocate values on the heap.
+//! * [`std::borrow`]::[`ToOwned`]: The conversion trait that defines
 //!   [`to_owned`], the generic method for creating an owned type from a
 //!   borrowed type.
-//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines
+//! * [`std::clone`]::[`Clone`]: The ubiquitous trait that defines
 //!   [`clone`][`Clone::clone`], the method for producing a copy of a value.
-//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }, the
+//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`]}: The
 //!   comparison traits, which implement the comparison operators and are often
 //!   seen in trait bounds.
-//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}, generic
+//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}: Generic
 //!   conversions, used by savvy API authors to create overloaded methods.
 //! * [`std::default`]::[`Default`], types that have default values.
-//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`]
-//!   [`DoubleEndedIterator`], [`ExactSizeIterator`]}, iterators of various
+//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`],
+//!   [`DoubleEndedIterator`], [`ExactSizeIterator`]}: Iterators of various
 //!   kinds.
 //! * [`std::option`]::[`Option`]::{[`self`][`Option`], [`Some`], [`None`]}, a
 //!   type which expresses the presence or absence of a value. This type is so
 //!   commonly used, its variants are also exported.
-//! * [`std::result`]::[`Result`]::{[`self`][`Result`], [`Ok`], [`Err`]}, a type
+//! * [`std::result`]::[`Result`]::{[`self`][`Result`], [`Ok`], [`Err`]}: A type
 //!   for functions that may succeed or fail. Like [`Option`], its variants are
 //!   exported as well.
-//! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings.
-//! * [`std::vec`]::[`Vec`], a growable, heap-allocated vector.
+//! * [`std::string`]::{[`String`], [`ToString`]}: Heap-allocated strings.
+//! * [`std::vec`]::[`Vec`]: A growable, heap-allocated vector.


it is better in lowercase, yes. I do like the : better than the , though, and being consistent is good.

The heading style for `std::prelude` is to be consistent with the headings for `std` and `core`: `# The Rust Standard Library` and `# The Rust Core Library`, respectively.

steveklabnik

Thank you so much!

steveklabnik · 2021-01-20T14:17:25Z

@bors: r+ rollup

bors · 2021-01-20T14:17:27Z

📌 Commit 25a4964 has been approved by steveklabnik

…ct, r=steveklabnik Use consistent punctuation for 'Prelude contents' docs

Rollup of 11 pull requests Successful merges: - rust-lang#79655 (Add Vec visualization to understand capacity) - rust-lang#80172 (Use consistent punctuation for 'Prelude contents' docs) - rust-lang#80429 (Add regression test for mutual recursion in obligation forest) - rust-lang#80601 (Improve grammar in documentation of format strings) - rust-lang#81046 (Improve unknown external crate error) - rust-lang#81178 (Visit only terminators when removing landing pads) - rust-lang#81179 (Fix broken links with `--document-private-items` in the standard library) - rust-lang#81184 (Remove unnecessary `after_run` function) - rust-lang#81185 (Fix ICE in mir when evaluating SizeOf on unsized type) - rust-lang#81187 (Fix typo in counters.rs) - rust-lang#81219 (Document security implications of std::env::temp_dir) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

rust-highfive assigned kennytm Dec 18, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 18, 2020

camelid added 2 commits December 18, 2020 15:05

Use consistent punctuation for 'Prelude contents' docs

c78bfba

Use heading style for 'The I/O Prelude' in std::io::prelude

4a6014b

camelid force-pushed the prelude-docs-consistent-punct branch from 3b7a797 to 4a6014b Compare December 18, 2020 23:06

camelid commented Dec 18, 2020

View reviewed changes

rust-highfive assigned steveklabnik and unassigned kennytm Dec 18, 2020

steveklabnik reviewed Dec 28, 2020

View reviewed changes

camelid added 2 commits January 5, 2021 17:51

Use lowercase for prelude items

4274ba4

Use heading for std::prelude and not io::prelude

25a4964

The heading style for `std::prelude` is to be consistent with the headings for `std` and `core`: `# The Rust Standard Library` and `# The Rust Core Library`, respectively.

steveklabnik reviewed Jan 20, 2021

View reviewed changes

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 Jan 20, 2021

m-ou-se added a commit to m-ou-se/rust that referenced this pull request Jan 20, 2021

Rollup merge of rust-lang#80172 - camelid:prelude-docs-consistent-pun…

9343d94

…ct, r=steveklabnik Use consistent punctuation for 'Prelude contents' docs

m-ou-se mentioned this pull request Jan 20, 2021

Rollup of 11 pull requests #81212

Closed

m-ou-se added a commit to m-ou-se/rust that referenced this pull request Jan 20, 2021

Rollup merge of rust-lang#80172 - camelid:prelude-docs-consistent-pun…

e7552d1

…ct, r=steveklabnik Use consistent punctuation for 'Prelude contents' docs

m-ou-se mentioned this pull request Jan 20, 2021

Rollup of 10 pull requests #81216

Closed

JohnTitor mentioned this pull request Jan 21, 2021

Rollup of 11 pull requests #81240

Merged

bors merged commit 9abd746 into rust-lang:master Jan 21, 2021

rustbot added this to the 1.51.0 milestone Jan 21, 2021

steffahn mentioned this pull request Jan 21, 2021

Make documentation of which items the prelude exports more readable. #80720

Merged

camelid deleted the prelude-docs-consistent-punct branch January 21, 2021 21:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use consistent punctuation for 'Prelude contents' docs #80172

Use consistent punctuation for 'Prelude contents' docs #80172

camelid commented Dec 18, 2020

rust-highfive commented Dec 18, 2020

camelid Dec 18, 2020

steveklabnik Dec 28, 2020

camelid commented Dec 18, 2020

steveklabnik left a comment

steveklabnik Dec 28, 2020

camelid Dec 28, 2020 •

edited

Loading

steveklabnik Jan 5, 2021

camelid Jan 6, 2021

steveklabnik Jan 11, 2021

camelid Jan 11, 2021

steveklabnik Dec 28, 2020

steveklabnik left a comment

steveklabnik commented Jan 20, 2021

bors commented Jan 20, 2021

Use consistent punctuation for 'Prelude contents' docs #80172

Use consistent punctuation for 'Prelude contents' docs #80172

Conversation

camelid commented Dec 18, 2020

rust-highfive commented Dec 18, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camelid commented Dec 18, 2020

steveklabnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camelid Dec 28, 2020 • edited Loading

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

steveklabnik left a comment

Choose a reason for hiding this comment

steveklabnik commented Jan 20, 2021

bors commented Jan 20, 2021

camelid Dec 28, 2020 •

edited

Loading