fixup some safety comments

Author: nia-e

library/alloc/src/collections/binary_heap/mod.rs

@@ -1530,11 +1530,13 @@ struct Hole<'a, T: 'a> {
 impl<'a, T> Hole<'a, T> {
     /// Creates a new `Hole` at index `pos`.
     ///
-    /// Unsafe because pos must be within the data slice.
+    /// # Safety
+    ///
+    /// `pos` must be within the data slice.
     #[inline]
     unsafe fn new(data: &'a mut [T], pos: usize) -> Self {
         debug_assert!(pos < data.len());
-        // SAFETY: pos should be inside the slice
+        // SAFETY: Caller ensures pos is inside the slice.
         let elt = unsafe { ptr::read(data.get_unchecked(pos)) };
         Hole { data, elt: ManuallyDrop::new(elt), pos }
     }
@@ -1553,6 +1555,7 @@ impl<'a, T> Hole<'a, T> {
     /// Returns a reference to the element at `index`.
     ///
     /// # Safety
+    ///
     /// `index` must be within the data slice and not equal to the current position.
     #[inline]
     unsafe fn get(&self, index: usize) -> &T {
@@ -1565,6 +1568,7 @@ impl<'a, T> Hole<'a, T> {
     /// Move hole to new location
     ///
     /// # Safety
+    ///
     /// `index` must be within the data slice and not equal to the current position.
     #[inline]
     unsafe fn move_to(&mut self, index: usize) {

library/alloc/src/collections/btree/mem.rs

@@ -23,7 +23,7 @@ pub(super) fn replace<T, R>(v: &mut T, change: impl FnOnce(T) -> (T, R)) -> R {
         }
     }
     let guard = PanicGuard;
-    // SAFETY: v is valid for reads.
+    // SAFETY: v is valid for reads and we write a new value before returning.
     let value = unsafe { ptr::read(v) };
     let (new_value, ret) = change(value);
     // SAFETY: new_value is T and v is valid for writes.

library/alloc/src/collections/vec_deque/mod.rs

@@ -1893,9 +1893,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
         // are valid ranges into the physical buffer, so
         // it's ok to pass them to `buffer_range` and
         // dereference the result.
-        let a = unsafe { &*self.buffer_range(a_range) };
-        // SAFETY: As above.
-        let b = unsafe { &*self.buffer_range(b_range) };
+        let (a, b) = unsafe { (&*self.buffer_range(a_range), &*self.buffer_range(b_range)) };
+
         Iter::new(a.iter(), b.iter())
     }
 
@@ -1930,13 +1929,13 @@ impl<T, A: Allocator> VecDeque<T, A> {
         R: RangeBounds<usize>,
     {
         let (a_range, b_range) = self.slice_ranges(range, self.len);
-        // SAFETY: The ranges returned by `slice_ranges`
-        // are valid ranges into the physical buffer, so
-        // it's ok to pass them to `buffer_range` and
-        // dereference the result.
-        let a = unsafe { &mut *self.buffer_range(a_range) };
-        // SAFETY: As above.
-        let b = unsafe { &mut *self.buffer_range(b_range) };
+        let (a, b) =
+            // SAFETY: The ranges returned by `slice_ranges`
+            // are valid ranges into the physical buffer, so
+            // it's ok to pass them to `buffer_range` and
+            // dereference the result.
+            unsafe { (&mut *self.buffer_range(a_range), &mut *self.buffer_range(b_range)) };
+
         IterMut::new(a.iter_mut(), b.iter_mut())
     }
 

library/alloc/src/sync.rs

@@ -4945,7 +4945,7 @@ impl<T: ?Sized, A: Allocator> UniqueArc<T, A> {
     #[cfg(not(no_global_oom_handling))]
     fn into_inner_with_allocator(this: Self) -> (NonNull<ArcInner<T>>, A) {
         let this = mem::ManuallyDrop::new(this);
-        // SAFETY: Pointer is valid for reads and won't be double-dropped.
+        // SAFETY: Pointer is valid for reads and only read once.
         (this.ptr, unsafe { ptr::read(&this.alloc) })
     }