Elaborate on SAFETY comments

2 files changed, 39 insertions, 37 deletions

diff --git a/src/libcore/str/lossy.rs b/src/libcore/str/lossy.rs
index 9d2e38734ef..88b2bc551b7 100644
--- a/src/libcore/str/lossy.rs
+++ b/src/libcore/str/lossy.rs
@@ -15,7 +15,7 @@ impl Utf8Lossy {
     }
 
     pub fn from_bytes(bytes: &[u8]) -> &Utf8Lossy {
-        // SAFETY: both use the same memory layout, and UTF-8 correctness isn't required
+        // SAFETY: Both use the same memory layout, and UTF-8 correctness isn't required.
         unsafe { mem::transmute(bytes) }
     }
 
@@ -59,7 +59,8 @@ impl<'a> Iterator for Utf8LossyChunksIter<'a> {
         while i < self.source.len() {
             let i_ = i;
 
-            // SAFETY: 0 <= i < self.source.len()
+            // SAFETY: `i` starts at `0`, is less than `self.source.len()`, and
+            // only increases, so `0 <= i < self.source.len()`.
             let byte = unsafe { *self.source.get_unchecked(i) };
             i += 1;
 
@@ -69,7 +70,7 @@ impl<'a> Iterator for Utf8LossyChunksIter<'a> {
 
                 macro_rules! error {
                     () => {{
-                        // SAFETY: we have checked up to `i` that source is valid UTF-8
+                        // SAFETY: We have checked up to `i` that source is valid UTF-8.
                         unsafe {
                             let r = Utf8LossyChunk {
                                 valid: core_str::from_utf8_unchecked(&self.source[0..i_]),
@@ -131,7 +132,7 @@ impl<'a> Iterator for Utf8LossyChunksIter<'a> {
         }
 
         let r = Utf8LossyChunk {
-            // SAFETY: we have checked that the entire source is valid UTF-8
+            // SAFETY: We have checked that the entire source is valid UTF-8.
             valid: unsafe { core_str::from_utf8_unchecked(self.source) },
             broken: &[],
         };
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index f89edf1910f..ec1713d1d4b 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -340,7 +340,7 @@ impl Utf8Error {
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
     run_utf8_validation(v)?;
-    // SAFETY: just ran validation
+    // SAFETY: Just ran validation.
     Ok(unsafe { from_utf8_unchecked(v) })
 }
 
@@ -379,7 +379,7 @@ pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
     run_utf8_validation(v)?;
-    // SAFETY: just ran validation
+    // SAFETY: Just ran validation.
     Ok(unsafe { from_utf8_unchecked_mut(v) })
 }
 
@@ -582,7 +582,7 @@ impl<'a> Iterator for Chars<'a> {
     #[inline]
     fn next(&mut self) -> Option<char> {
         next_code_point(&mut self.iter).map(|ch| {
-            // SAFETY: str invariant says `ch` is a valid Unicode Scalar Value
+            // SAFETY: `str` invariant says `ch` is a valid Unicode Scalar Value.
             unsafe { char::from_u32_unchecked(ch) }
         })
     }
@@ -629,7 +629,7 @@ impl<'a> DoubleEndedIterator for Chars<'a> {
     #[inline]
     fn next_back(&mut self) -> Option<char> {
         next_code_point_reverse(&mut self.iter).map(|ch| {
-            // SAFETY: str invariant says `ch` is a valid Unicode Scalar Value
+            // SAFETY: `str` invariant says `ch` is a valid Unicode Scalar Value.
             unsafe { char::from_u32_unchecked(ch) }
         })
     }
@@ -659,7 +659,7 @@ impl<'a> Chars<'a> {
     #[stable(feature = "iter_to_slice", since = "1.4.0")]
     #[inline]
     pub fn as_str(&self) -> &'a str {
-        // SAFETY: `Chars` is only made from a str, which guarantees the iter is valid utf8
+        // SAFETY: `Chars` is only made from a str, which guarantees the iter is valid UTF-8.
         unsafe { from_utf8_unchecked(self.iter.as_slice()) }
     }
 }
@@ -1104,7 +1104,7 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
     fn get_end(&mut self) -> Option<&'a str> {
         if !self.finished && (self.allow_trailing_empty || self.end - self.start > 0) {
             self.finished = true;
-            // SAFETY: `self.start` and `self.end` always lie on unicode boundaries
+            // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
             unsafe {
                 let string = self.matcher.haystack().get_unchecked(self.start..self.end);
                 Some(string)
@@ -1122,7 +1122,7 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
 
         let haystack = self.matcher.haystack();
         match self.matcher.next_match() {
-            // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries
+            // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries.
             Some((a, b)) => unsafe {
                 let elt = haystack.get_unchecked(self.start..a);
                 self.start = b;
@@ -1155,13 +1155,13 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
 
         let haystack = self.matcher.haystack();
         match self.matcher.next_match_back() {
-            // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries
+            // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries.
             Some((a, b)) => unsafe {
                 let elt = haystack.get_unchecked(b..self.end);
                 self.end = a;
                 Some(elt)
             },
-            // SAFETY: `self.start` and `self.end` always lie on unicode boundaries
+            // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
             None => unsafe {
                 self.finished = true;
                 Some(haystack.get_unchecked(self.start..self.end))
@@ -1301,7 +1301,7 @@ where
 impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
     #[inline]
     fn next(&mut self) -> Option<(usize, &'a str)> {
-        // SAFETY: `Searcher` guaratees that `start` and `end` lie on unicode boundaries
+        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
         self.0
             .next_match()
             .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
@@ -1312,7 +1312,7 @@ impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
     where
         P::Searcher: ReverseSearcher<'a>,
     {
-        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries
+        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
         self.0
             .next_match_back()
             .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
@@ -1356,7 +1356,7 @@ where
 impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
     #[inline]
     fn next(&mut self) -> Option<&'a str> {
-        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries
+        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
         self.0.next_match().map(|(a, b)| unsafe {
             // Indices are known to be on utf8 boundaries
             self.0.haystack().get_unchecked(a..b)
@@ -1368,7 +1368,7 @@ impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
     where
         P::Searcher: ReverseSearcher<'a>,
     {
-        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries
+        // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
         self.0.next_match_back().map(|(a, b)| unsafe {
             // Indices are known to be on utf8 boundaries
             self.0.haystack().get_unchecked(a..b)
@@ -1589,9 +1589,10 @@ fn run_utf8_validation(v: &[u8]) -> Result<(), Utf8Error> {
             if align != usize::max_value() && align.wrapping_sub(index) % usize_bytes == 0 {
                 let ptr = v.as_ptr();
                 while index < blocks_end {
-                    // SAFETY: since `align - index` and `ascii_block_size` are multiples of
-                    // `usize_bytes`, `ptr.add(index)` is always aligned with a `usize` so we
-                    // may cast directly to a `const` pointer.
+                    // SAFETY: since `align - index` and `ascii_block_size` are
+                    // multiples of `usize_bytes`, `block = ptr.add(index)` is
+                    // always aligned with a `usize` so it's safe to dereference
+                    // both `block` and `block.offset(1)`.
                     unsafe {
                         let block = ptr.add(index) as *const usize;
                         // break if there is a nonascii byte
@@ -1817,7 +1818,7 @@ mod traits {
                 && slice.is_char_boundary(self.start)
                 && slice.is_char_boundary(self.end)
             {
-                // SAFETY: just checked that `start` and `end` are on a char boundary
+                // SAFETY: just checked that `start` and `end` are on a char boundary.
                 Some(unsafe { self.get_unchecked(slice) })
             } else {
                 None
@@ -1829,7 +1830,7 @@ mod traits {
                 && slice.is_char_boundary(self.start)
                 && slice.is_char_boundary(self.end)
             {
-                // SAFETY: just checked that `start` and `end` are on a char boundary
+                // SAFETY: just checked that `start` and `end` are on a char boundary.
                 Some(unsafe { self.get_unchecked_mut(slice) })
             } else {
                 None
@@ -1860,7 +1861,7 @@ mod traits {
                 && slice.is_char_boundary(self.start)
                 && slice.is_char_boundary(self.end)
             {
-                // SAFETY: just checked that `start` and `end` are on a char boundary
+                // SAFETY: just checked that `start` and `end` are on a char boundary.
                 unsafe { self.get_unchecked_mut(slice) }
             } else {
                 super::slice_error_fail(slice, self.start, self.end)
@@ -1889,7 +1890,7 @@ mod traits {
         #[inline]
         fn get(self, slice: &str) -> Option<&Self::Output> {
             if slice.is_char_boundary(self.end) {
-                // SAFETY: just checked that `end` is on a char boundary
+                // SAFETY: just checked that `end` is on a char boundary.
                 Some(unsafe { self.get_unchecked(slice) })
             } else {
                 None
@@ -1898,7 +1899,7 @@ mod traits {
         #[inline]
         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
             if slice.is_char_boundary(self.end) {
-                // SAFETY: just checked that `end` is on a char boundary
+                // SAFETY: just checked that `end` is on a char boundary.
                 Some(unsafe { self.get_unchecked_mut(slice) })
             } else {
                 None
@@ -1922,7 +1923,7 @@ mod traits {
         #[inline]
         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
             if slice.is_char_boundary(self.end) {
-                // SAFETY: just checked that `end` is on a char boundary
+                // SAFETY: just checked that `end` is on a char boundary.
                 unsafe { self.get_unchecked_mut(slice) }
             } else {
                 super::slice_error_fail(slice, 0, self.end)
@@ -1952,7 +1953,7 @@ mod traits {
         #[inline]
         fn get(self, slice: &str) -> Option<&Self::Output> {
             if slice.is_char_boundary(self.start) {
-                // SAFETY: just checked that `start` is on a char boundary
+                // SAFETY: just checked that `start` is on a char boundary.
                 Some(unsafe { self.get_unchecked(slice) })
             } else {
                 None
@@ -1961,7 +1962,7 @@ mod traits {
         #[inline]
         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
             if slice.is_char_boundary(self.start) {
-                // SAFETY: just checked that `start` is on a char boundary
+                // SAFETY: just checked that `start` is on a char boundary.
                 Some(unsafe { self.get_unchecked_mut(slice) })
             } else {
                 None
@@ -1987,7 +1988,7 @@ mod traits {
         #[inline]
         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
             if slice.is_char_boundary(self.start) {
-                // SAFETY: just checked that `start` is on a char boundary
+                // SAFETY: just checked that `start` is on a char boundary.
                 unsafe { self.get_unchecked_mut(slice) }
             } else {
                 super::slice_error_fail(slice, self.start, slice.len())
@@ -2593,7 +2594,7 @@ impl str {
     pub fn split_at(&self, mid: usize) -> (&str, &str) {
         // is_char_boundary checks that the index is in [0, .len()]
         if self.is_char_boundary(mid) {
-            // SAFETY: just checked that `mid` is on a char boundary
+            // SAFETY: just checked that `mid` is on a char boundary.
             unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
         } else {
             slice_error_fail(self, 0, mid)
@@ -2638,7 +2639,7 @@ impl str {
         if self.is_char_boundary(mid) {
             let len = self.len();
             let ptr = self.as_mut_ptr();
-            // SAFETY: just checked that `mid` is on a char boundary
+            // SAFETY: just checked that `mid` is on a char boundary.
             unsafe {
                 (
                     from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
@@ -3827,7 +3828,7 @@ impl str {
         if let Some((_, b)) = matcher.next_reject_back() {
             j = b;
         }
-        // SAFETY: `Searcher` is known to return valid indices
+        // SAFETY: `Searcher` is known to return valid indices.
         unsafe {
             self.get_unchecked(i..j)
         }
@@ -3866,7 +3867,7 @@ impl str {
         if let Some((a, _)) = matcher.next_reject() {
             i = a;
         }
-        // SAFETY: `Searcher` is known to return valid indices
+        // SAFETY: `Searcher` is known to return valid indices.
         unsafe {
             self.get_unchecked(i..self.len())
         }
@@ -3992,7 +3993,7 @@ impl str {
         if let Some((_, b)) = matcher.next_reject_back() {
             j = b;
         }
-        // SAFETY: `Searcher` is known to return valid indices
+        // SAFETY: `Searcher` is known to return valid indices.
         unsafe {
             self.get_unchecked(0..j)
         }
@@ -4188,7 +4189,7 @@ impl str {
     /// ```
     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
     pub fn make_ascii_uppercase(&mut self) {
-        // SAFETY: safe because we transmute two types with the same layout
+        // SAFETY: safe because we transmute two types with the same layout.
         let me = unsafe { self.as_bytes_mut() };
         me.make_ascii_uppercase()
     }
@@ -4214,7 +4215,7 @@ impl str {
     /// ```
     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
     pub fn make_ascii_lowercase(&mut self) {
-        // SAFETY: safe because we transmute two types with the same layout
+        // SAFETY: safe because we transmute two types with the same layout.
         let me = unsafe { self.as_bytes_mut() };
         me.make_ascii_lowercase()
     }
@@ -4380,7 +4381,7 @@ impl Default for &str {
 #[stable(feature = "default_mut_str", since = "1.28.0")]
 impl Default for &mut str {
     /// Creates an empty mutable str
-    // SAFETY: `str` is guranteed to be UTF-8
+    // SAFETY: `str` is guranteed to be UTF-8.
     fn default() -> Self {
         unsafe { from_utf8_unchecked_mut(&mut []) }
     }