Document all unsafe blocks

There were several unsafe blocks in the existing implementation that
were not documented with a SAFETY comment.

Author: Voultapher

library/core/src/slice/sort.rs

@@ -940,6 +940,7 @@ where
     F: FnMut(&T, &T) -> bool,
 {
     if v.len() >= 2 && is_less(&v[1], &v[0]) {
+        // SAFETY: Copy tmp back even if panic, and ensure unique observation.
         unsafe {
             // There are three ways to implement insertion here:
             //
@@ -992,6 +993,7 @@ where
 
     impl<T> Drop for InsertionHole<T> {
         fn drop(&mut self) {
+            // SAFETY: The caller must ensure that src and dest are correctly set.
             unsafe {
                 ptr::copy_nonoverlapping(self.src, self.dest, 1);
             }
@@ -1012,6 +1014,8 @@ where
 {
     let len = v.len();
     let v = v.as_mut_ptr();
+
+    // SAFETY: mid and len must be in-bounds of v.
     let (v_mid, v_end) = unsafe { (v.add(mid), v.add(len)) };
 
     // The merge process first copies the shorter run into `buf`. Then it traces the newly copied
@@ -1035,6 +1039,8 @@ where
 
     if mid <= len - mid {
         // The left run is shorter.
+
+        // SAFETY: buf must have enough capacity for `v[..mid]`.
         unsafe {
             ptr::copy_nonoverlapping(v, buf, mid);
             hole = MergeHole { start: buf, end: buf.add(mid), dest: v };
@@ -1048,6 +1054,8 @@ where
         while *left < hole.end && right < v_end {
             // Consume the lesser side.
             // If equal, prefer the left run to maintain stability.
+
+            // SAFETY: left and right must be valid and part of v same for out.
             unsafe {
                 let to_copy = if is_less(&*right, &**left) {
                     get_and_increment(&mut right)
@@ -1059,6 +1067,8 @@ where
         }
     } else {
         // The right run is shorter.
+
+        // SAFETY: buf must have enough capacity for `v[mid..]`.
         unsafe {
             ptr::copy_nonoverlapping(v_mid, buf, len - mid);
             hole = MergeHole { start: buf, end: buf.add(len - mid), dest: v_mid };
@@ -1072,6 +1082,8 @@ where
         while v < *left && buf < *right {
             // Consume the greater side.
             // If equal, prefer the right run to maintain stability.
+
+            // SAFETY: left and right must be valid and part of v same for out.
             unsafe {
                 let to_copy = if is_less(&*right.sub(1), &*left.sub(1)) {
                     decrement_and_get(left)
@@ -1087,11 +1099,14 @@ where
 
     unsafe fn get_and_increment<T>(ptr: &mut *mut T) -> *mut T {
         let old = *ptr;
+
+        // SAFETY: ptr.add(1) must still be a valid pointer and part of `v`.
         *ptr = unsafe { ptr.add(1) };
         old
     }
 
     unsafe fn decrement_and_get<T>(ptr: &mut *mut T) -> *mut T {
+        // SAFETY: ptr.sub(1) must still be a valid pointer and part of `v`.
         *ptr = unsafe { ptr.sub(1) };
         *ptr
     }
@@ -1105,7 +1120,7 @@ where
 
     impl<T> Drop for MergeHole<T> {
         fn drop(&mut self) {
-            // `T` is not a zero-sized type, and these are pointers into a slice's elements.
+            // SAFETY: `T` is not a zero-sized type, and these are pointers into a slice's elements.
             unsafe {
                 let len = self.end.sub_ptr(self.start);
                 ptr::copy_nonoverlapping(self.start, self.dest, len);
@@ -1180,6 +1195,8 @@ pub fn merge_sort<T, CmpF, ElemAllocF, ElemDeallocF, RunAllocF, RunDeallocF>(
         let mut start = end - 1;
         if start > 0 {
             start -= 1;
+
+            // SAFETY: The v.get_unchecked must be fed with correct inbound indicies.
             unsafe {
                 if is_less(v.get_unchecked(start + 1), v.get_unchecked(start)) {
                     while start > 0 && is_less(v.get_unchecked(start), v.get_unchecked(start - 1)) {
@@ -1210,6 +1227,8 @@ pub fn merge_sort<T, CmpF, ElemAllocF, ElemDeallocF, RunAllocF, RunDeallocF>(
         while let Some(r) = collapse(runs.as_slice()) {
             let left = runs[r + 1];
             let right = runs[r];
+            // SAFETY: `buf_ptr` must hold enough capacity for the shorter of the two sides, and
+            // neither side may be on length 0.
             unsafe {
                 merge(&mut v[left.start..right.start + right.len], left.len, buf_ptr, is_less);
             }