Use consistent punctuation for 'Prelude contents' docs #80172
Conversation
|
r? @kennytm (rust-highfive has picked a reviewer for you, use r? to override) |
3b7a797 to
4a6014b
Compare
library/std/src/prelude/mod.rs
Outdated
| //! * [`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. |
There was a problem hiding this comment.
It might be better in lowercase, but either way I think it should be consistent among all of these items.
There was a problem hiding this comment.
it is better in lowercase, yes. I do like the : better than the , though, and being consistent is good.
|
r? @steveklabnik maybe? |
library/std/src/io/prelude.rs
Outdated
| @@ -1,4 +1,4 @@ | |||
| //! The I/O Prelude | |||
| //! # The I/O Prelude | |||
There was a problem hiding this comment.
Why is this change being made?
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
library/std/src/prelude/mod.rs
Outdated
| //! * [`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. |
There was a problem hiding this comment.
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.
|
@bors: r+ rollup |
|
📌 Commit 25a4964 has been approved by |
…ct, r=steveklabnik Use consistent punctuation for 'Prelude contents' docs
…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
No description provided.