From 7885c7b7b235dac038859abb3664760cda1fbd98 Mon Sep 17 00:00:00 2001
From: Zachary S <zasample18+github@gmail.com>
Date: Sun, 9 Jun 2024 20:47:46 -0500
Subject: [PATCH 1/2] Update safety docs for AtomicBool::from_ptr.

Clarify that alignment is never an issue, since `align_of::<AtomicBool>() == 1`.
---
 library/core/src/sync/atomic.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs
index 482bd19705c2f..21cd4f1500926 100644
--- a/library/core/src/sync/atomic.rs
+++ b/library/core/src/sync/atomic.rs
@@ -443,8 +443,8 @@ impl AtomicBool {
     ///
     /// # Safety
     ///
-    /// * `ptr` must be aligned to `align_of::<AtomicBool>()` (note that on some platforms this can
-    ///   be bigger than `align_of::<bool>()`).
+    /// * `ptr` must be aligned to `align_of::<AtomicBool>()` (note that this is always true, since
+    ///   `align_of::<AtomicBool>() == 1`).
     /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`.
     /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not
     ///   allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes,

From 2d4cb7aa5ae86a7fca57d80e7a0d6acdf79fa64e Mon Sep 17 00:00:00 2001
From: Zachary S <zasample18+github@gmail.com>
Date: Sun, 9 Jun 2024 21:15:48 -0500
Subject: [PATCH 2/2] Update docs for AtomicU8/I8.

Clarify that they always have the same alignment as u8/i8, (unlike other atomic types).
Clarify in from_ptr that alignment is never an issue because of this.
---
 library/core/src/sync/atomic.rs | 46 ++++++++++++++++++++++-----------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs
index 21cd4f1500926..03af574094855 100644
--- a/library/core/src/sync/atomic.rs
+++ b/library/core/src/sync/atomic.rs
@@ -2091,10 +2091,10 @@ impl<T> From<*mut T> for AtomicPtr<T> {
 }
 
 #[allow(unused_macros)] // This macro ends up being unused on some architectures.
-macro_rules! if_not_8_bit {
-    (u8, $($tt:tt)*) => { "" };
-    (i8, $($tt:tt)*) => { "" };
-    ($_:ident, $($tt:tt)*) => { $($tt)* };
+macro_rules! if_8_bit {
+    (u8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
+    (i8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
+    ($_:ident, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($no)*)?) };
 }
 
 #[cfg(target_has_atomic_load_store)]
@@ -2116,18 +2116,24 @@ macro_rules! atomic_int {
      $int_type:ident $atomic_type:ident) => {
         /// An integer type which can be safely shared between threads.
         ///
-        /// This type has the same size and bit validity as the underlying
-        /// integer type, [`
+        /// This type has the same
+        #[doc = if_8_bit!(
+            $int_type,
+            yes = ["size, alignment, and bit validity"],
+            no = ["size and bit validity"],
+        )]
+        /// as the underlying integer type, [`
         #[doc = $s_int_type]
         /// `].
-        #[doc = if_not_8_bit! {
+        #[doc = if_8_bit! {
             $int_type,
-            concat!(
+            no = [
                 "However, the alignment of this type is always equal to its ",
                 "size, even on targets where [`", $s_int_type, "`] has a ",
                 "lesser alignment."
-            )
+            ],
         }]
+        ///
         /// For more about the differences between atomic types and
         /// non-atomic types as well as information about the portability of
         /// this type, please see the [module-level documentation].
@@ -2220,9 +2226,19 @@ macro_rules! atomic_int {
             ///
             /// # Safety
             ///
-            #[doc = concat!(" * `ptr` must be aligned to \
-                `align_of::<", stringify!($atomic_type), ">()` (note that on some platforms this \
-                can be bigger than `align_of::<", stringify!($int_type), ">()`).")]
+            /// * `ptr` must be aligned to
+            #[doc = concat!("  `align_of::<", stringify!($atomic_type), ">()`")]
+            #[doc = if_8_bit!{
+                $int_type,
+                yes = [
+                    "  (note that this is always true, since `align_of::<",
+                    stringify!($atomic_type), ">() == 1`)."
+                ],
+                no = [
+                    "  (note that on some platforms this can be bigger than `align_of::<",
+                    stringify!($int_type), ">()`)."
+                ],
+            }]
             /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`.
             /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not
             ///   allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes,
@@ -2261,12 +2277,12 @@ macro_rules! atomic_int {
 
             #[doc = concat!("Get atomic access to a `&mut ", stringify!($int_type), "`.")]
             ///
-            #[doc = if_not_8_bit! {
+            #[doc = if_8_bit! {
                 $int_type,
-                concat!(
+                no = [
                     "**Note:** This function is only available on targets where `",
                     stringify!($int_type), "` has an alignment of ", $align, " bytes."
-                )
+                ],
             }]
             ///
             /// # Examples