Added an example of usage where an unsafe block is not required

Author: madhav-madhusoodanan

library/core/src/sync/atomic.rs

@@ -3402,11 +3402,8 @@ macro_rules! atomic_int {
             /// This method is mostly useful for FFI, where the function signature may use
             #[doc = concat!("`*mut ", stringify!($int_type), "` instead of `&", stringify!($atomic_type), "`.")]
             ///
-            /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the
-            /// atomic types work with interior mutability. All modifications of an atomic change the value
-            /// through a shared reference, and can do so safely as long as they use atomic operations. Any
-            /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same
-            /// restriction: operations on it must not lead to data races.
+            /// All modifications of an atomic change the value through a shared reference, and can do so safely
+            /// as long as they use atomic operations.
             ///
             /// # Examples
             ///
@@ -3420,12 +3417,24 @@ macro_rules! atomic_int {
             ///
             #[doc = concat!("let atomic = ", stringify!($atomic_type), "::new(1);")]
             ///
-            /// // SAFETY: Safe as long as `my_atomic_op` does not lead to a data race.
+            /// // SAFETY: `my_atomic_op` only uses atomic operations so it will not lead to a data race.
             /// unsafe {
             ///     my_atomic_op(atomic.as_ptr());
             /// }
             /// # }
             /// ```
+            ///
+            /// ```
+            #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")]
+            ///
+            ///
+            #[doc = concat!("let atomic_ref_1 = ", stringify!($atomic_type), "::new(1);")]
+            #[doc = concat!("let atomic_ref_2 = ", stringify!($atomic_type), "::new(2);")]
+            ///
+            /// // Comparison of addresses is a safe operation and does not require an `unsafe` block.
+            /// let is_equal = atomic_ref_1 == atomic_ref_2;
+            /// assert!(is_equal || !is_equal);
+            /// ```
             #[inline]
             #[stable(feature = "atomic_as_ptr", since = "1.70.0")]
             #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")]