Skip to content

Use consistent punctuation for 'Prelude contents' docs #80172

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Jan 21, 2021
Merged

Use consistent punctuation for 'Prelude contents' docs #80172

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c78bfba
Use consistent punctuation for 'Prelude contents' docs
camelid Dec 18, 2020
4a6014b
Use heading style for 'The I/O Prelude' in `std::io::prelude`
camelid Dec 18, 2020
4274ba4
Use lowercase for prelude items
camelid Jan 6, 2021
25a4964
Use heading for `std::prelude` and not `io::prelude`
camelid Jan 6, 2021
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion library/std/src/io/prelude.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! The I/O Prelude
//! # The I/O Prelude
Copy link
Contributor

@steveklabnik steveklabnik Dec 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this change being made?
Copy link
Member Author

@camelid camelid Dec 28, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

image

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).
Copy link
Contributor

@steveklabnik steveklabnik Jan 5, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member Author

@camelid camelid Jan 6, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

@steveklabnik steveklabnik Jan 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member Author

@camelid camelid Jan 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
//!
//! The purpose of this module is to alleviate imports of many common I/O traits
//! by adding a glob import to the top of I/O heavy modules:
Expand Down
28 changes: 14 additions & 14 deletions library/std/src/prelude/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,35 +28,35 @@
//! The current version of the prelude (version 1) lives in
//! [`std::prelude::v1`], and re-exports the following:
//!
//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`], [`Unpin`]},
//! marker traits that indicate fundamental properties of types.
//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}, various
//! * [`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.
Copy link
Member Author

@camelid camelid Dec 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@steveklabnik steveklabnik Dec 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is better in lowercase, yes. I do like the : better than the , though, and being consistent is good.
//!
//! [`mem::drop`]: crate::mem::drop
//! [`std::borrow`]: crate::borrow
Expand Down