Fix doc nits

[bitfield]

Many tiny changes to stdlib doc comments to make them consistent (for example "Returns foo", rather than "Return foo"), adding missing periods, paragraph breaks, backticks for monospace style, and other minor nits.

[rustbot]

r? @jhpratt

rustbot has assigned @jhpratt.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred to the platform-builtins intrinsics. Make sure the
LLVM backend as well as portable-simd gets adapted for the changes.

cc @antoyo, @GuillaumeGomez, @bjorn3, @calebzulawski, @programmerjake

Portable SIMD is developed in its own repository. If possible, consider making this change to rust-lang/portable-simd instead.

cc @calebzulawski, @programmerjake

[tgross35]

This is great, but covers a ton of area. Could you split it up into a separate PR for each crate (or smaller yet) so it is easier to review and get through?

[bors]

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

[jhpratt]

r? libs

I won't have time in the near future to review this (even if split up).

[bitfield]

Could you split it up into a separate PR for each crate (or smaller yet)

@joboet what's your preference? Since this is primarily about consistency between crates, and across the documentation as a whole, it made sense to me to submit a single PR.

If @tgross35 is right that it should be split, I'm happy to re-submit this as forty separate PRs, one per crate, or even one hundred and forty-seven separate PRs, one for each file. I just want to confirm that this will really reduce your workload as a reviewer.

If not, I appreciate your kindness in reviewing the diff as it stands.

[joboet]

In imperative-style programming, which Rust follows, the program is a sequence of instructions to the computer. With the current documentation style, you could replace the function calls with the first line of the documentation and the code would still make sense. Take for example

std::alloc::alloc(layout);

What is it that you tell the computer to do?

Allocate memory with the global allocator.

I find this style much cleaner. Of course, this is subjective, but this is what has been established in std and thus much of the ecosystem. Feel free to open an issue if you want to make your point, but I will not accept this PR until consensus has been reached that we want this.

There are some very reasonable changes in here as well, feel free to submit a PR only containing those.

[bitfield]

Of course, this is subjective, but this is what has been established in std and thus much of the ecosystem. Feel free to open an issue if you want to make your point, but I will not accept this PR until consensus has been reached that we want this.

Thanks, @joboet. Like you, I can see the arguments for that style of documentation comment—shall we call it the "Allocate" style, as opposed to the alternative "Allocates" style?

I'm personally neutral about this: either style would work for me, but I put a high value on consistency: I try to use either one style or the other throughout a particular codebase.

I'll let others weigh in on what they think the right style is for the Rust standard library, but a couple of points that might be worth considering in favour of the "Allocates" style are:

• The Rust Book uses this style in its example doc comments
• The majority—I think, on a casual survey, the vast majority—of the stdlib code uses this style too. Indeed, it was not easy to track down many examples of the alternate style to fix in this PR.

For example, here are the first words of each of the doc comments for the current set of macros in std (if they start with a verb):

Asserts
Asserts
Asserts
Evaluates
Expands
Causes
Concatenates
Prints
Asserts
Asserts
Asserts
Inspects
Prints
Prints
Expands
Creates
Constructs
Parses
Includes
Includes
Expands
Returns
Expands
Panics
Prints
Prints
Stringifies
Declare
Indicates
Unwraps
Indicates
Indicates
Creates
Writes
Write
Concatenates
Concatenates
Prints
Enables

I make it 37 for the "Allocates" style, and only 2 for the "Allocate" style—it doesn't seem unreasonable to assume that this 95% — 5% split applies roughly equally across the standard library. To be clear, this PR proposes that the 5% be updated to match the 95%: I think you are suggesting that it should be the other way round. If I've got that wrong, please correct me.

If the consensus is that all the "Allocates" comments should be changed to "Allocate" style, then I'm equally happy to help with that work too, but it would be, of course, a much bigger change and a much bigger job.

For additional reference, this topic was also discussed in #4361, a consensus apparently reached (in favour of "Allocates"), and a similar PR (#16241) to change "Allocate" to "Allocates" where necessary was accepted and merged.

[bors]

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

[joboet]

Those are from 2014, I'm not sure whether that's still our policy.

@rustbot label +I-libs-api-nominated
or maybe this is a question for T-style?

[joshtriplett]

We reviewed this in today's libs-api meeting. Apparently we have a previously accepted RFC that specifically recommends the other way, and as @bitfield noted, much of the library is consistent with that. See https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text for that convention.

We may want to put those conventions somewhere more visible.

[bitfield]

Thanks @joshtriplett—I had a feeling I'd seen this text somewhere, but couldn't track it down. As you say, maybe there are ways we could make it more visible—a mention in the book, perhaps.

@joboet, if you're satisfied that the RFC establishes a consensus for the main changes in this PR, it's ready for you to take another look at, as soon as you can spare the time. I appreciate your guidance.

[bors]

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

[dtolnay]

Thank you! This is terrific.

[dtolnay]

@bors r+

[bors]

📌 Commit a19472a has been approved by dtolnay

It is now in the queue for this repository.