Document why as_mut_ptr is safe

diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs
index 5d6972bf75c7966939153ef286b8e96c1c4d7d7e..3a5b4135a917c2180468ff69762d9896e55fe57a 100644 (file)
--- a/src/libcore/sync/atomic.rs
+++ b/src/libcore/sync/atomic.rs
@@ -809,6 +809,12 @@ pub fn fetch_xor(&self, val: bool, order: Ordering) -> bool {
     /// This method is mostly useful for FFI, where the function signature may use
     /// `*mut bool` instead of `&AtomicBool`.
     ///
+    /// 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 be atomic.
+    ///
     /// [`bool`]: ../../../std/primitive.bool.html
     ///
     /// # Examples
@@ -1929,6 +1935,12 @@ pub fn fetch_min(&self, val: $int_type, order: Ordering) -> $int_type {
 This method is mostly useful for FFI, where the function signature may use
 `*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 be atomic.
+
 # Examples
 
 ```ignore (extern-declaration)