From 50d0bea15384f1116afd6831de3cbdc8c154e677 Mon Sep 17 00:00:00 2001
From: Ben Kimock <kimockb@gmail.com>
Date: Sat, 9 Mar 2024 10:49:26 -0500
Subject: [PATCH] Improve docs

---
 library/core/src/intrinsics.rs | 15 +++++++++------
 library/core/src/ptr/mod.rs    |  3 +--
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/library/core/src/intrinsics.rs b/library/core/src/intrinsics.rs
index eda8b7842ab..7cda1225672 100644
--- a/library/core/src/intrinsics.rs
+++ b/library/core/src/intrinsics.rs
@@ -2799,6 +2799,10 @@ pub(crate) use assert_unsafe_precondition;
 
 /// Checks whether `ptr` is properly aligned with respect to
 /// `align_of::<T>()`.
+///
+/// In `const` this is approximate and can fail spuriously. It is primarily intended
+/// for `assert_unsafe_precondition!` with `check_language_ub`, in which case the
+/// check is anyway not executed in `const`.
 #[inline]
 pub(crate) const fn is_aligned_and_not_null(ptr: *const (), align: usize) -> bool {
     !ptr.is_null() && ptr.is_aligned_to(align)
@@ -2813,10 +2817,10 @@ pub(crate) const fn is_valid_allocation_size(size: usize, len: usize) -> bool {
 /// Checks whether the regions of memory starting at `src` and `dst` of size
 /// `count * size` do *not* overlap.
 ///
-/// # Safety
-/// This function must only be called such that if it returns false, we will execute UB.
+/// Note that in const-eval this function just returns `true` and therefore must
+/// only be used with `assert_unsafe_precondition!`, similar to `is_aligned_and_not_null`.
 #[inline]
-pub(crate) const unsafe fn is_nonoverlapping(
+pub(crate) const fn is_nonoverlapping(
     src: *const (),
     dst: *const (),
     size: usize,
@@ -2842,7 +2846,7 @@ pub(crate) const unsafe fn is_nonoverlapping(
         true
     }
 
-    #[cfg_attr(not(bootstrap), allow(unused_unsafe))]
+    #[cfg_attr(not(bootstrap), allow(unused_unsafe))] // on bootstrap bump, remove unsafe block
     // SAFETY: This function's precondition is equivalent to that of `const_eval_select`.
     // Programs which do not execute UB will only see this function return `true`, which makes the
     // const and runtime implementation indistinguishable.
@@ -2962,8 +2966,7 @@ pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: us
         ) =>
         is_aligned_and_not_null(src, align)
             && is_aligned_and_not_null(dst, align)
-            // SAFETY: If this returns false, we're about to execute UB.
-            && unsafe { is_nonoverlapping(src, dst, size, count) }
+            && is_nonoverlapping(src, dst, size, count)
     );
 
     // SAFETY: the safety contract for `copy_nonoverlapping` must be
diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs
index 80a6d5779e1..30af7522368 100644
--- a/library/core/src/ptr/mod.rs
+++ b/library/core/src/ptr/mod.rs
@@ -1032,8 +1032,7 @@ pub const unsafe fn swap_nonoverlapping<T>(x: *mut T, y: *mut T, count: usize) {
         ) =>
         is_aligned_and_not_null(x, align)
             && is_aligned_and_not_null(y, align)
-            // SAFETY: If this returns false, we're about to execute UB.
-            && unsafe { is_nonoverlapping(x, y, size, count) }
+            && is_nonoverlapping(x, y, size, count)
     );
 
     // Split up the slice into small power-of-two-sized chunks that LLVM is able