From ad0ec749ceb53497d7532cae422cc896f08735e5 Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Tue, 23 Jun 2026 14:55:20 -0400
Subject: [PATCH 1/7] refactor: move attribute and keywords docs files to core

---
 library/{std => core}/src/attribute_docs.rs |  0
 library/{std => core}/src/keyword_docs.rs   |  0
 library/core/src/lib.rs                     | 15 +++++++++++++++
 library/std/src/lib.rs                      | 17 +++++++++--------
 4 files changed, 24 insertions(+), 8 deletions(-)
 rename library/{std => core}/src/attribute_docs.rs (100%)
 rename library/{std => core}/src/keyword_docs.rs (100%)

diff --git a/library/std/src/attribute_docs.rs b/library/core/src/attribute_docs.rs
similarity index 100%
rename from library/std/src/attribute_docs.rs
rename to library/core/src/attribute_docs.rs
diff --git a/library/std/src/keyword_docs.rs b/library/core/src/keyword_docs.rs
similarity index 100%
rename from library/std/src/keyword_docs.rs
rename to library/core/src/keyword_docs.rs
diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs
index a26304c46ecea..73480c891ca78 100644
--- a/library/core/src/lib.rs
+++ b/library/core/src/lib.rs
@@ -397,4 +397,19 @@ pub mod simd {
     pub use crate::core_simd::simd::*;
 }
 
+// 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!("attribute_docs.rs");
+
+// Include a number of private modules that exist solely to provide
+// the rustdoc documentation for the existing keywords. Using `include!`
+// because rustdoc only looks for these modules at the crate level.
+include!("keyword_docs.rs");
+
+// Include a number of private modules that exist solely to provide
+// the rustdoc documentation for primitive types. Using `include!`
+// because rustdoc only looks for these modules at the crate level.
 include!("primitive_docs.rs");
+
+
diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs
index 1b27be8e2dde3..939f1c8e855dc 100644
--- a/library/std/src/lib.rs
+++ b/library/std/src/lib.rs
@@ -778,20 +778,21 @@ pub mod from {
     pub use core::from::From;
 }
 
+// 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");
+
 // Include a number of private modules that exist solely to provide
-// the rustdoc documentation for primitive types. Using `include!`
+// the rustdoc documentation for the existing keywords. Using `include!`
 // because rustdoc only looks for these modules at the crate level.
-include!("../../core/src/primitive_docs.rs");
+include!("../../core/src/keyword_docs.rs");
 
 // Include a number of private modules that exist solely to provide
-// the rustdoc documentation for the existing keywords. Using `include!`
+// the rustdoc documentation for primitive types. Using `include!`
 // because rustdoc only looks for these modules at the crate level.
-include!("keyword_docs.rs");
+include!("../../core/src/primitive_docs.rs");
 
-// 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!("attribute_docs.rs");
 
 // This is required to avoid an unstable error when `restricted-std` is not
 // enabled. The use of #![feature(restricted_std)] in rustc-std-workspace-std

From f8abac3ba613f160c2511a6c13a4c3006ac99d91 Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Tue, 23 Jun 2026 15:38:55 -0400
Subject: [PATCH 2/7] fix references to `std`

---
 library/core/src/keyword_docs.rs | 69 +++++++++++++++-----------------
 1 file changed, 32 insertions(+), 37 deletions(-)

diff --git a/library/core/src/keyword_docs.rs b/library/core/src/keyword_docs.rs
index 5f94a13dad22a..924c78c773ee0 100644
--- a/library/core/src/keyword_docs.rs
+++ b/library/core/src/keyword_docs.rs
@@ -195,7 +195,7 @@ mod break_keyword {}
 /// to be most things that would be reasonable to have in a constant (barring `const fn`s). For
 /// example, you can't have a [`File`] as a `const`.
 ///
-/// [`File`]: crate::fs::File
+/// [`File`]: ../std/fs/struct.File.html
 ///
 /// The only lifetime allowed in a constant is `'static`, which is the lifetime that encompasses
 /// all others in a Rust program. For example, if you wanted to define a constant string, it would
@@ -484,7 +484,7 @@ mod extern_keyword {}
 
 #[doc(keyword = "false")]
 //
-/// A value of type [`bool`] representing logical **false**.
+/// A value of type [`prim@bool`] representing logical **false**.
 ///
 /// `false` is the logical opposite of [`true`].
 ///
@@ -1235,31 +1235,18 @@ mod ref_keyword {}
 /// `return` returns from the function immediately (an "early return"):
 ///
 /// ```no_run
-/// use std::fs::File;
-/// use std::io::{Error, ErrorKind, Read, Result};
+/// fn main() -> Result<(), &'static str> {
+///    let contents = "Hello, world!";
 ///
-/// fn main() -> Result<()> {
-///     let mut file = match File::open("foo.txt") {
-///         Ok(f) => f,
-///         Err(e) => return Err(e),
-///     };
-///
-///     let mut contents = String::new();
-///     let size = match file.read_to_string(&mut contents) {
-///         Ok(s) => s,
-///         Err(e) => return Err(e),
-///     };
+///    if contents.contains("impossible!") {
+///        return Err("oh no!");
+///    }
 ///
-///     if contents.contains("impossible!") {
-///         return Err(Error::new(ErrorKind::Other, "oh no!"));
-///     }
-///
-///     if size > 9000 {
-///         return Err(Error::new(ErrorKind::Other, "over 9000!"));
-///     }
+///    if contents.len() > 9000 {
+///        return Err("over 9000!");
+///    }
 ///
-///     assert_eq!(contents, "Hello, world!");
-///     Ok(())
+///    Ok(())
 /// }
 /// ```
 ///
@@ -1631,8 +1618,8 @@ mod self_upper_keyword {}
 /// [`extern`]: keyword.extern.html
 /// [`mut`]: keyword.mut.html
 /// [`unsafe`]: keyword.unsafe.html
-/// [`Mutex`]: sync::Mutex
-/// [`OnceLock`]: sync::OnceLock
+/// [`Mutex`]: ../std/sync/struct.Mutex.html
+/// [`OnceLock`]: ../std/sync/struct.OnceLock.html
 /// [`RefCell`]: cell::RefCell
 /// [atomic]: sync::atomic
 /// [Reference]: ../reference/items/static-items.html
@@ -1959,7 +1946,7 @@ mod trait_keyword {}
 
 #[doc(keyword = "true")]
 //
-/// A value of type [`bool`] representing logical **true**.
+/// A value of type [`prim@bool`] representing logical **true**.
 ///
 /// Logically `true` is not equal to [`false`].
 ///
@@ -2146,22 +2133,30 @@ mod type_keyword {}
 /// Since `unsafe fn` and `unsafe trait` indicate that there is a safety
 /// 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
 /// that must be fulfilled to safely call the function.
 ///
 /// ```rust,ignore (stub-to-show-doc-example)
-/// /// Forces the length of the vector to `new_len`.
+/// /// Moves `src` into the pointed `dst`, returning the previous `dst` value.
 /// ///
-/// /// This is a low-level operation that maintains none of the normal
-/// /// invariants of the type. Normally changing the length of a vector
-/// /// is done using one of the safe operations instead, such as
-/// /// `truncate`, `resize`, `extend`, or `clear`.
+/// /// Neither value is dropped.
+/// ///
+/// /// This function is semantically equivalent to [`mem::replace`] except that it
+/// /// operates on raw pointers instead of references. When references are
+/// /// available, [`mem::replace`] should be preferred.
 /// ///
 /// /// # Safety
 /// ///
-/// /// - `new_len` must be less than or equal to `capacity()`.
-/// /// - The elements at `old_len..new_len` must be initialized.
-/// pub unsafe fn set_len(&mut self, new_len: usize)
+/// /// Behavior is undefined if any of the following conditions are violated:
+/// ///
+/// /// * `dst` must be [valid] for both reads and writes or `T` must be a ZST.
+/// ///
+/// /// * `dst` must be properly aligned.
+/// ///
+/// /// * `dst` must point to a properly initialized value of type `T`.
+/// ///
+/// /// Note that even if `T` has size `0`, the pointer must be properly aligned.
+/// pub const unsafe fn replace<T>(dst: *mut T, src: T) -> T
 /// ```
 ///
 /// ## Using `unsafe {}` blocks and `impl`s
@@ -2502,7 +2497,7 @@ mod use_keyword {}
 /// ```
 ///
 /// `where` is available anywhere generic and lifetime parameters are available,
-/// as can be seen with the [`Cow`](crate::borrow::Cow) type from the standard
+/// as can be seen with the [`Cow`](../std/borrow/enum.Cow.html) type from the standard
 /// library:
 ///
 /// ```rust

From 05922ef423539eb538fb263a37ee817f2f756d4b Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Tue, 23 Jun 2026 15:40:55 -0400
Subject: [PATCH 3/7] tidy fixes

---
 library/core/src/lib.rs | 2 --
 library/std/src/lib.rs  | 1 -
 2 files changed, 3 deletions(-)

diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs
index 73480c891ca78..124e871a32a3a 100644
--- a/library/core/src/lib.rs
+++ b/library/core/src/lib.rs
@@ -411,5 +411,3 @@ include!("keyword_docs.rs");
 // the rustdoc documentation for primitive types. Using `include!`
 // because rustdoc only looks for these modules at the crate level.
 include!("primitive_docs.rs");
-
-
diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs
index 939f1c8e855dc..ff572c4ef8938 100644
--- a/library/std/src/lib.rs
+++ b/library/std/src/lib.rs
@@ -793,7 +793,6 @@ include!("../../core/src/keyword_docs.rs");
 // because rustdoc only looks for these modules at the crate level.
 include!("../../core/src/primitive_docs.rs");
 
-
 // This is required to avoid an unstable error when `restricted-std` is not
 // enabled. The use of #![feature(restricted_std)] in rustc-std-workspace-std
 // is unconditional, so the unstable feature needs to be defined somewhere.

From a40f3d577b7458cc5bb51cfa9e1d41a581a3f137 Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Thu, 25 Jun 2026 23:40:26 -0400
Subject: [PATCH 4/7] ignore doc tests w/ explicit_tail_calls

---
 library/core/src/keyword_docs.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/library/core/src/keyword_docs.rs b/library/core/src/keyword_docs.rs
index 924c78c773ee0..ed32df655dcd0 100644
--- a/library/core/src/keyword_docs.rs
+++ b/library/core/src/keyword_docs.rs
@@ -1293,7 +1293,7 @@ mod return_keyword {}
 /// manner to computed goto).
 ///
 /// Example of using `become` to implement functional-style `fold`:
-/// ```
+/// ```ignore (explicit_tail_calls not supported on wasm targets)
 /// #![feature(explicit_tail_calls)]
 /// #![expect(incomplete_features)]
 ///
@@ -1347,7 +1347,7 @@ mod return_keyword {}
 ///    (unless it's coerced to a function pointer)
 ///
 /// It is possible to tail-call a function pointer:
-/// ```
+/// ```ignore (explicit_tail_calls not supported on wasm targets)
 /// #![feature(explicit_tail_calls)]
 /// #![expect(incomplete_features)]
 ///

From 5b094ee34dd15d089dda62abdadc619c2d00d90c Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Sat, 27 Jun 2026 13:09:39 -0400
Subject: [PATCH 5/7] revert `unsafe` example and ignore specifically WASM for
 `become` doc tests

---
 library/core/src/keyword_docs.rs | 33 +++++++++++++++-----------------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/library/core/src/keyword_docs.rs b/library/core/src/keyword_docs.rs
index ed32df655dcd0..ac4fb427c8d69 100644
--- a/library/core/src/keyword_docs.rs
+++ b/library/core/src/keyword_docs.rs
@@ -1293,7 +1293,11 @@ mod return_keyword {}
 /// manner to computed goto).
 ///
 /// Example of using `become` to implement functional-style `fold`:
-/// ```ignore (explicit_tail_calls not supported on wasm targets)
+#[cfg_attr(
+    target_family = "wasm",
+    doc = "```ignore (tail-call target feature not enabled by default on wasm)"
+)]
+#[cfg_attr(not(target_family = "wasm"), doc = "```")]
 /// #![feature(explicit_tail_calls)]
 /// #![expect(incomplete_features)]
 ///
@@ -2133,30 +2137,22 @@ mod type_keyword {}
 /// Since `unsafe fn` and `unsafe trait` indicate that there is a safety
 /// 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 [`ptr::replace`]. The `# Safety` section explains the contract
+/// extract from [`Vec::set_len`]. The `# Safety` section explains the contract
 /// that must be fulfilled to safely call the function.
 ///
 /// ```rust,ignore (stub-to-show-doc-example)
-/// /// Moves `src` into the pointed `dst`, returning the previous `dst` value.
-/// ///
-/// /// Neither value is dropped.
+/// /// Forces the length of the vector to `new_len`.
 /// ///
-/// /// This function is semantically equivalent to [`mem::replace`] except that it
-/// /// operates on raw pointers instead of references. When references are
-/// /// available, [`mem::replace`] should be preferred.
+/// /// This is a low-level operation that maintains none of the normal
+/// /// invariants of the type. Normally changing the length of a vector
+/// /// is done using one of the safe operations instead, such as
+/// /// `truncate`, `resize`, `extend`, or `clear`.
 /// ///
 /// /// # Safety
 /// ///
-/// /// Behavior is undefined if any of the following conditions are violated:
-/// ///
-/// /// * `dst` must be [valid] for both reads and writes or `T` must be a ZST.
-/// ///
-/// /// * `dst` must be properly aligned.
-/// ///
-/// /// * `dst` must point to a properly initialized value of type `T`.
-/// ///
-/// /// Note that even if `T` has size `0`, the pointer must be properly aligned.
-/// pub const unsafe fn replace<T>(dst: *mut T, src: T) -> T
+/// /// - `new_len` must be less than or equal to `capacity()`.
+/// /// - The elements at `old_len..new_len` must be initialized.
+/// pub unsafe fn set_len(&mut self, new_len: usize)
 /// ```
 ///
 /// ## Using `unsafe {}` blocks and `impl`s
@@ -2307,6 +2303,7 @@ mod type_keyword {}
 /// [`static`]: keyword.static.html
 /// [`union`]: keyword.union.html
 /// [`impl`]: keyword.impl.html
+/// [`Vec::set_len`]: ../std/vec/struct.Vec.html#method.set_len
 /// [raw pointers]: ../reference/types/pointer.html
 /// [memory safety]: ../book/ch19-01-unsafe-rust.html
 /// [Rustonomicon]: ../nomicon/index.html

From 9eb0ce48014e18ef7b39063dc397ca10e336e059 Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Sat, 27 Jun 2026 13:12:49 -0400
Subject: [PATCH 6/7] add explicit note about doube including the docs in
 `core` and `std`

---
 library/std/src/lib.rs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs
index ff572c4ef8938..f24ce720e944f 100644
--- a/library/std/src/lib.rs
+++ b/library/std/src/lib.rs
@@ -778,7 +778,10 @@ pub mod from {
     pub use core::from::From;
 }
 
-// Include private modules that exist solely to provide rustdoc
+// We include the following files here *again* (they are already included in libcore)
+// so that they show up in search results for the std crate, and to avoid breaking
+// existing links:
+
 // documentation for built-in attributes. Using `include!` because rustdoc
 // only looks for these modules at the crate level.
 include!("../../core/src/attribute_docs.rs");

From b050ccff9b341c89997be2f9ad977f9ab4ca3a00 Mon Sep 17 00:00:00 2001
From: Justin Schilleman <justin@schilleman.com>
Date: Sat, 27 Jun 2026 13:16:48 -0400
Subject: [PATCH 7/7] missed refactoring of doc test ignore

---
 library/core/src/keyword_docs.rs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/library/core/src/keyword_docs.rs b/library/core/src/keyword_docs.rs
index ac4fb427c8d69..8f84a05f3e794 100644
--- a/library/core/src/keyword_docs.rs
+++ b/library/core/src/keyword_docs.rs
@@ -1351,7 +1351,11 @@ mod return_keyword {}
 ///    (unless it's coerced to a function pointer)
 ///
 /// It is possible to tail-call a function pointer:
-/// ```ignore (explicit_tail_calls not supported on wasm targets)
+#[cfg_attr(
+    target_family = "wasm",
+    doc = "```ignore (tail-call target feature not enabled by default on wasm)"
+)]
+#[cfg_attr(not(target_family = "wasm"), doc = "```")]
 /// #![feature(explicit_tail_calls)]
 /// #![expect(incomplete_features)]
 ///