Fix soundness issues and improve safety comments

Author: vks

src/distr/integer.rs

@@ -119,7 +119,7 @@ impl Distribution<__m128i> for StandardUniform {
         rng.fill_bytes(&mut buf);
         // x86 is little endian so no need for conversion
 
-        // SAFETY: both source and result types are valid for all values.
+        // SAFETY: All representations of the source are also representations of the target.
         unsafe { core::mem::transmute(buf) }
     }
 }
@@ -132,7 +132,7 @@ impl Distribution<__m256i> for StandardUniform {
         rng.fill_bytes(&mut buf);
         // x86 is little endian so no need for conversion
 
-        // SAFETY: both source and result types are valid for all values.
+        // SAFETY: All representations of the source are also representations of the target.
         unsafe { core::mem::transmute(buf) }
     }
 }
@@ -148,7 +148,7 @@ impl Distribution<__m512i> for StandardUniform {
         rng.fill_bytes(&mut buf);
         // x86 is little endian so no need for conversion
 
-        // SAFETY: both source and result types are valid for all values.
+        // SAFETY: All representations of the source are also representations of the target.
         unsafe { core::mem::transmute(buf) }
     }
 }

src/distr/other.rs

@@ -118,6 +118,7 @@ impl Distribution<char> for StandardUniform {
         if n <= 0xDFFF {
             n -= GAP_SIZE;
         }
+        // SAFETY: The representation of `n` is a valid representation of `u32`.
         unsafe { char::from_u32_unchecked(n) }
     }
 }
@@ -166,6 +167,7 @@ impl Distribution<u8> for Alphabetic {
 #[cfg(feature = "alloc")]
 impl SampleString for Alphanumeric {
     fn append_string<R: Rng + ?Sized>(&self, rng: &mut R, string: &mut String, len: usize) {
+        // SAFETY: `self` only samples alphanumeric characters, which are valid UTF-8.
         unsafe {
             let v = string.as_mut_vec();
             v.extend(self.sample_iter(rng).take(len));

src/lib.rs

@@ -59,6 +59,7 @@
     clippy::neg_cmp_op_on_partial_ord,
     clippy::nonminimal_bool
 )]
+#![deny(clippy::undocumented_unsafe_blocks)]
 
 #[cfg(feature = "alloc")]
 extern crate alloc;

src/rng.rs

@@ -393,20 +393,26 @@ impl Fill for [u8] {
     }
 }
 
-// This macro is unsafe to call: target types must support transmute from
-// random bits (i.e. all bit representations are valid).
+/// Implement `Fill` for given type `T`.
+///
+/// # Safety
+/// All representations of `[u8; size_of::<T>()]` are also representations of `T`.
 macro_rules! unsafe_impl_fill {
     () => {};
     ($t:ty) => {
         impl Fill for [$t] {
             fn fill<R: Rng + ?Sized>(&mut self, rng: &mut R) {
                 if self.len() > 0 {
-                    rng.fill_bytes(unsafe {
-                        slice::from_raw_parts_mut(self.as_mut_ptr()
-                            as *mut u8,
-                            mem::size_of_val(self)
-                        )
-                    });
+                    let size = mem::size_of_val(self);
+                    rng.fill_bytes(
+                        // SAFETY: `self` is not borrowed and all byte sequences are representations of `T`.
+                        unsafe {
+                            slice::from_raw_parts_mut(self.as_mut_ptr()
+                                as *mut u8,
+                                size
+                            )
+                        }
+                    );
                     for x in self {
                         *x = x.to_le();
                     }
@@ -417,12 +423,16 @@ macro_rules! unsafe_impl_fill {
         impl Fill for [Wrapping<$t>] {
             fn fill<R: Rng + ?Sized>(&mut self, rng: &mut R) {
                 if self.len() > 0 {
-                    rng.fill_bytes(unsafe {
-                        slice::from_raw_parts_mut(self.as_mut_ptr()
-                            as *mut u8,
-                            self.len() * mem::size_of::<$t>()
-                        )
-                    });
+                    let size = self.len() * mem::size_of::<$t>();
+                    rng.fill_bytes(
+                        // SAFETY: `self` is not borrowed and all byte sequences are representations of `T`.
+                        unsafe {
+                            slice::from_raw_parts_mut(self.as_mut_ptr()
+                                as *mut u8,
+                                size
+                            )
+                        }
+                    );
                     for x in self {
                         *x = Wrapping(x.0.to_le());
                     }
@@ -438,7 +448,9 @@ macro_rules! unsafe_impl_fill {
     }
 }
 
+// SAFETY: All representations of `[u8; size_of::<u*>()]` are representations of `u*`.
 unsafe_impl_fill!(u16, u32, u64, u128,);
+// SAFETY: All representations of `[u8; size_of::<i*>()]` are representations of `i*`.
 unsafe_impl_fill!(i8, i16, i32, i64, i128,);
 
 impl<T, const N: usize> Fill for [T; N]