From b84f9813618e6d8de68e91022e942562940a83cc Mon Sep 17 00:00:00 2001
From: LeSeulArtichaut <leseulartichaut@gmail.com>
Date: Sun, 12 Apr 2020 16:47:57 +0200
Subject: [PATCH] Document unsafety in `src/libcore/hash/sip.rs`

---
 src/libcore/hash/sip.rs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs
index adfbe243512..ac058609f45 100644
--- a/src/libcore/hash/sip.rs
+++ b/src/libcore/hash/sip.rs
@@ -1,7 +1,5 @@
 //! An implementation of SipHash.
 
-// ignore-tidy-undocumented-unsafe
-
 #![allow(deprecated)] // the types in this module are deprecated
 
 use crate::cmp;
@@ -265,6 +263,7 @@ fn write(&mut self, msg: &[u8]) {
 
         if self.ntail != 0 {
             needed = 8 - self.ntail;
+            // SAFETY: `cmp::min(length, needed)` is guaranteed to not be over `length`
             self.tail |= unsafe { u8to64_le(msg, 0, cmp::min(length, needed)) } << (8 * self.ntail);
             if length < needed {
                 self.ntail += length;
@@ -279,10 +278,13 @@ fn write(&mut self, msg: &[u8]) {
 
         // Buffered tail is now flushed, process new input.
         let len = length - needed;
-        let left = len & 0x7;
+        let left = len & 0x7; // len % 8
 
         let mut i = needed;
         while i < len - left {
+            // SAFETY: because `len - left` is the biggest multiple of 8 under
+            // `len`, and because `i` starts at `needed` where `len` is `length - needed`,
+            // `i + 8` is guaranteed to be less than or equal to `length`.
             let mi = unsafe { load_int_le!(msg, i, u64) };
 
             self.state.v3 ^= mi;
@@ -292,6 +294,9 @@ fn write(&mut self, msg: &[u8]) {
             i += 8;
         }
 
+        // SAFETY: `i` is now `needed + len.div_euclid(8) * 8`,
+        // so `i + left` = `needed + len` = `length`, which is by
+        // definition equal to `msg.len()`.
         self.tail = unsafe { u8to64_le(msg, i, left) };
         self.ntail = left;
     }