Move attribute and keyword docs from `std` to `core` by jschillem · Pull Request #158327 · rust-lang/rust

jschillem · 2026-06-23T19:54:24Z

Move the documentation for attributes and keywords into the core crate. Apart from strictly moving the module, I had to make a few small changes to certain docs to avoid using std types when possible, as well as fixing a few suggestions related to linking to primitives.

Pre-requisite for work on #157604.

r? @GuillaumeGomez

Verified documentation using:
./x doc library/core and ./x doc library/std, as well as running doc-tests for both crates.

rustbot · 2026-06-23T19:54:29Z

Thanks for the pull request, and welcome! The Rust Project is excited to review your changes, and you should hear from @GuillaumeGomez (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

@rustbot author: the review is finished, PR author should check the comments and take action accordingly
@rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

GuillaumeGomez · 2026-06-24T10:14:49Z

Thanks!

@bors r+ rollup

rust-bors · 2026-06-24T10:14:52Z

📌 Commit e5d79ed has been approved by GuillaumeGomez

It is now in the queue for this repository.

@GuillaumeGomez

…-keywords-to-core, r=GuillaumeGomez Move attribute and keyword docs from `std` to `core` Move the documentation for attributes and keywords into the `core` crate. Apart from strictly moving the module, I had to make a few small changes to certain docs to avoid using `std` types when possible, as well as fixing a few suggestions related to linking to primitives. Pre-requisite for work on rust-lang#157604. r? @GuillaumeGomez Verified documentation using: `./x doc library/core` and `./x doc library/std`, as well as running doc-tests for both crates.

@GuillaumeGomez

…-keywords-to-core, r=GuillaumeGomez Move attribute and keyword docs from `std` to `core` Move the documentation for attributes and keywords into the `core` crate. Apart from strictly moving the module, I had to make a few small changes to certain docs to avoid using `std` types when possible, as well as fixing a few suggestions related to linking to primitives. Pre-requisite for work on rust-lang#157604. r? @GuillaumeGomez Verified documentation using: `./x doc library/core` and `./x doc library/std`, as well as running doc-tests for both crates.

JonathanBrouwer · 2026-06-25T07:55:08Z

💔 I suspect this PR failed tests as part of a rollup
@bors r-

After fixing the problem, consider running a try job for the failed job before re-approving.

Link to failure: #158389 (comment)

rust-bors · 2026-06-25T07:55:17Z

This pull request was unapproved.

This PR was contained in a rollup (#158389), which was unapproved.

View changes since this unapproval

GuillaumeGomez · 2026-06-25T14:14:46Z

@bors try job=test-various

…o-core, r=<try> Move attribute and keyword docs from `std` to `core` try-job: test-various

rust-bors · 2026-06-25T15:02:09Z

💔 Test for 6850d53 failed: CI. Failed job:

try - test-various (web logs, enhanced plaintext logs)

rust-bors · 2026-06-25T16:37:09Z

@jschillem: 🔑 Insufficient privileges: not in try users

rustbot · 2026-06-26T03:35:21Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rustbot · 2026-06-26T03:43:34Z

Error: Label Ameta can only be set by Rust team members

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

jschillem · 2026-06-26T03:45:54Z

Sorry about all the extra labels being added and comments! Borked a rebase 😅

RalfJung · 2026-06-26T06:41:00Z

 ///
 /// Example of using `become` to implement functional-style `fold`:
-/// ```
+/// ```ignore (explicit_tail_calls not supported on wasm targets)


This looks like a test coverage regression, since it will be ignored on all targets now

View changes since the review

Is there a way to ignore a doc test for a specific target?

When these docs were in std, the test did not run for the wasm32-wasip1 target in CI. However in core it does. The log of the failed try run earlier indicated that the explicit_tail_calls feature is not supported for this target.

Yes:

#[cfg_attr(target_os = "linux", doc = "```")] #[cfg_attr(not(target_os = "linux"), doc = "```ignore (not supporting on this target)")]

RalfJung · 2026-06-26T06:43:57Z

 /// contract that the compiler cannot enforce, documenting it is important. The
 /// standard library has many examples of this, like the following which is an
-/// extract from [`Vec::set_len`]. The `# Safety` section explains the contract
+/// extract from [`ptr::replace`]. The `# Safety` section explains the contract


I'd prefer to stick to the original example here -- ptr::replace is a raw pointer method which "feels" quite different from an unsafe method on a typically "safe" type. Also ptr::replace's condition is harder to understand.

View changes since the review

I agree and the goal with changing it was to make the example reference an unsafe method in core instead of std.

I spoke with @GuillaumeGomez about this AlPR. With the move to core, ideally the examples should minimize links to std.

I'll try and find a simpler method in core, and revert if I can't find one.

I don't think we should artificially limit our discussion of things like the unsafe keyword to examples that can be found in core. Instead, we should write the best docs we can write, using examples from any part of the standard library. unsafe is a language keyword, it's not part of any library, it's placement in core vs std is entirely incidental.

Arguably these docs really should be in the Reference, and then obviously they could use examples from std.

RalfJung · 2026-06-26T06:45:41Z

+// Include private modules that exist solely to provide rustdoc
+// documentation for built-in attributes. Using `include!` because rustdoc
+// only looks for these modules at the crate level.
+include!("../../core/src/attribute_docs.rs");


Why are these files included both in libcore and libstd? I guess this is to keep existing links like https://doc.rust-lang.org/nightly/std/keyword.unsafe.html working?

View changes since the review

This pattern was in place for the primitives docs already.

I spoke with some folks during the lang-docs office hour and the assumption is for visibility. Most people will be looking in the std documentation, however it should likely be in both. Additionally yes to avoid breaking existing links.

When you are in the std docs, you have access to core in any case, so no need to make them appear in both core and std.

This pattern was in place for the primitives docs already.

Yeah I saw that.

Still, would be good to add a brief comment explaining it.

Including in both was already set for primitive_docs.rs. I'm assuming this was added for just visibility reasons. But removing attributes and keywords from also being included in std, should I leave primitive_docs.rs included?

That will mean that looking for fn or any other items will show two items in the search results. Not great.

Thinking out loud, infra team can likely add redirections for these items.

That will mean that looking for fn or any other items will show two items in the search results. Not great.

Would it? We don't get duplicates for e.g. bool currently.

I believe it's only searching in the crate you're in currently. So if if the includes are removed from std, these docs will not be searchable. The user would have to explicitly go to core to find them.

So I don't believe it's show up twice. If anything removing from std would reduce overall visibility as most people are already searching within std.

Would it? We don't get duplicates for e.g. bool currently.

Ah indeed. That is... surprising. Oh well, if it works let's use it then. =D

rust-bors · 2026-06-27T04:56:01Z

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

rustbot assigned GuillaumeGomez Jun 23, 2026

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 23, 2026

GuillaumeGomez approved these changes Jun 24, 2026

View reviewed changes

rust-bors Bot 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 Jun 24, 2026

JonathanBrouwer mentioned this pull request Jun 25, 2026

Rollup of 18 pull requests #158386

Closed

JonathanBrouwer mentioned this pull request Jun 25, 2026

Rollup of 17 pull requests #158389

Closed

rust-bors Bot 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-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Jun 25, 2026

This comment has been minimized.

Sign in to view

rustbot added the has-merge-commits PR has merge commits, merge with caution. label Jun 25, 2026

jschillem force-pushed the docs-move-attributes-and-keywords-to-core branch from 2ce02ed to 8230837 Compare June 25, 2026 13:16

rustbot removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. has-merge-commits PR has merge commits, merge with caution. labels Jun 25, 2026

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request Jun 25, 2026

Auto merge of #158327 - jschillem:docs-move-attributes-and-keywords-t…

6850d53

…o-core, r=<try> Move attribute and keyword docs from `std` to `core` try-job: test-various

rust-bors Bot added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Jun 25, 2026

This comment has been minimized.

Sign in to view

jschillem force-pushed the docs-move-attributes-and-keywords-to-core branch from 059494a to 5ebd7f2 Compare June 26, 2026 03:32

jschillem added 3 commits June 25, 2026 23:34

refactor: move attribute and keywords docs files to core

d4d5160

fix references to std

68fb401

tidy fixes

471fbdf

jschillem force-pushed the docs-move-attributes-and-keywords-to-core branch from 5ebd7f2 to 471fbdf Compare June 26, 2026 03:35

ignore doc tests w/ explicit_tail_calls

8e77041

RalfJung reviewed Jun 26, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

jschillem commented Jun 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jun 23, 2026

Uh oh!

GuillaumeGomez commented Jun 24, 2026

Uh oh!

rust-bors Bot commented Jun 24, 2026

Uh oh!

JonathanBrouwer commented Jun 25, 2026

Uh oh!

rust-bors Bot commented Jun 25, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jun 25, 2026

Uh oh!

This comment has been minimized.

rust-bors Bot commented Jun 25, 2026

Uh oh!

This comment has been minimized.

rust-bors Bot commented Jun 25, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

rustbot commented Jun 26, 2026

Uh oh!

rustbot commented Jun 26, 2026

Uh oh!

jschillem commented Jun 26, 2026

Uh oh!

RalfJung Jun 26, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Jun 26, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Jun 26, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jschillem Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rust-bors Bot commented Jun 27, 2026

Uh oh!

Reviewers

Assignees

jschillem commented Jun 23, 2026 •

edited by rustbot

Loading

RalfJung Jun 26, 2026 •

edited by rustbot

Loading

RalfJung Jun 26, 2026 •

edited by rustbot

Loading

RalfJung Jun 26, 2026 •

edited

Loading

RalfJung Jun 26, 2026 •

edited by rustbot

Loading

jschillem Jun 26, 2026 •

edited

Loading