Adress feedback in #433

Author: samuelselleck

src/lib.rs

@@ -652,10 +652,10 @@ impl_known_layout!(const N: usize, T => [T; N]);
 
 safety_comment! {
     /// SAFETY:
-    // TODO(#429): Add reference to docs + quotes
     /// `str` and `ManuallyDrop<[T]>` have the same representations as `[u8]`
     /// and `[T]` repsectively. `str` has different bit validity than `[u8]`,
     /// but that doesn't affect the soundness of this impl.
+    /// TODO(#429): Add references to docs and quotes.
     unsafe_impl_known_layout!(#[repr([u8])] str);
     unsafe_impl_known_layout!(T: ?Sized + KnownLayout => #[repr(T)] ManuallyDrop<T>);
 }
@@ -757,13 +757,13 @@ pub unsafe trait FromZeroes {
         let slf: *mut Self = self;
         let len = mem::size_of_val(self);
         // SAFETY:
-        // TODO(#429): Add reference to docs + quotes
         // - `self` is guaranteed by the type system to be valid for writes of
         //   size `size_of_val(self)`.
         // - `u8`'s alignment is 1, and thus `self` is guaranteed to be aligned
         //   as required by `u8`.
         // - Since `Self: FromZeroes`, the all-zeroes instance is a valid
         //   instance of `Self.`
+        // TODO(#429): Add references to docs and quotes.
         unsafe { ptr::write_bytes(slf.cast::<u8>(), 0, len) };
     }
 
@@ -1145,7 +1145,6 @@ pub unsafe trait AsBytes {
         let slf: *const Self = self;
 
         // SAFETY:
-        // TODO(#429): Add reference to docs + quotes
         // - `slf.cast::<u8>()` is valid for reads for `len *
         //   mem::size_of::<u8>()` many bytes because...
         //   - `slf` is the same pointer as `self`, and `self` is a reference
@@ -1164,6 +1163,7 @@ pub unsafe trait AsBytes {
         // - The total size of the resulting slice is no larger than
         //   `isize::MAX` because no allocation produced by safe code can be
         //   larger than `isize::MAX`.
+        // TODO(#429): Add references to docs and quotes.
         unsafe { slice::from_raw_parts(slf.cast::<u8>(), len) }
     }
 
@@ -1199,6 +1199,7 @@ pub unsafe trait AsBytes {
         // - The total size of the resulting slice is no larger than
         //   `isize::MAX` because no allocation produced by safe code can be
         //   larger than `isize::MAX`.
+        // TODO(#429): Add references to docs and quotes.
         unsafe { slice::from_raw_parts_mut(slf.cast::<u8>(), len) }
     }
 
@@ -1286,7 +1287,6 @@ safety_comment! {
 
 safety_comment! {
     /// SAFETY:
-    /// TODO(#429): Add quotes
     /// - `FromZeroes`, `FromBytes`: all bit patterns are valid for integers [1]
     /// - `AsBytes`: integers have no padding bytes [1]
     /// - `Unaligned` (`u8` and `i8` only): The reference [2] specifies the size
@@ -1296,6 +1296,8 @@ safety_comment! {
     ///   - The only value >= 1 for which 1 is an integer multiple is 1
     ///   Therefore, the only possible alignment for `u8` and `i8` is 1.
     ///
+    /// TODO(#429): Add quotes from documentation.
+    ///
     /// [1] TODO(https://github.com/rust-lang/reference/issues/1291): Once the
     ///     reference explicitly guarantees these properties, cite it.
     /// [2] https://doc.rust-lang.org/reference/type-layout.html#primitive-data-layout
@@ -1322,8 +1324,9 @@ safety_comment! {
     /// - `AsBytes`: the `{f32,f64}::to_bits` methods' documentation [4,5]
     ///   states that they are currently equivalent to `transmute`. [3]
     ///
-    /// TODO(#429): Make these arguments more precisely in terms of the documentation
-    /// TODO(#429): Add quotes
+    /// TODO(#429):
+    /// - Make these arguments more precisely in terms of the documentation.
+    /// - Add quotes from documentation.
     ///
     /// [1] https://doc.rust-lang.org/nightly/std/primitive.f32.html#method.from_bits
     /// [2] https://doc.rust-lang.org/nightly/std/primitive.f64.html#method.from_bits
@@ -1337,11 +1340,12 @@ safety_comment! {
 
 safety_comment! {
     /// SAFETY:
-    /// - `FromZeroes`: Valid since "The value false has the bit pattern 0x00" [1].
-    /// - `AsBytes`: Since "the boolean type has a size and
-    ///   alignment of 1 each" and "The value false has the bit pattern 0x00 and
-    ///   the value true has the bit pattern 0x01" [1]. Note that it is undefined
-    ///   behavior for an object with the boolean type to have any other bit pattern.
+    /// - `FromZeroes`: Valid since "The value false has the bit pattern
+    ///   0x00" [1].
+    /// - `AsBytes`: Since "the boolean type has a size and alignment of 1 each"
+    ///   and "The value false has the bit pattern 0x00 and the value true has
+    ///   the bit pattern 0x01" [1]. Thus, the only byte of the bool is always
+    ///   initialized.
     /// - `Unaligned`: Per the reference [1], "[a]n object with the boolean type
     ///   has a size and alignment of 1 each."
     ///
@@ -1351,28 +1355,28 @@ safety_comment! {
 }
 safety_comment! {
     /// SAFETY:
-    /// - `FromZeroes`: Per reference [1], "A value of type char is
-    ///   a Unicode scalar value (i.e. a code point that is not a surrogate),
-    ///   represented as a 32-bit unsigned word in the 0x0000 to 0xD7FF or 0xE000
-    ///   to 0x10FFFF range" which contains 0x0000.
-    /// - `AsBytes`: `char` is per reference [1] "represented as a 32-bit unsigned
-    ///   word" (`u32`)
-    ///   which is `AsBytes`. Note that unlike `u32`, not all bit patterns
-    ///   are valid for `char`.
+    /// - `FromZeroes`: Per reference [1], "A value of type char is a Unicode
+    ///   scalar value (i.e. a code point that is not a surrogate), represented
+    ///   as a 32-bit unsigned word in the 0x0000 to 0xD7FF or 0xE000 to
+    ///   0x10FFFF range" which contains 0x0000.
+    /// - `AsBytes`: `char` is per reference [1] "represented as a 32-bit
+    ///   unsigned word" (`u32`) which is `AsBytes`. Note that unlike `u32`, not
+    ///   all bit patterns are valid for `char`.
     ///
     /// [1] https://doc.rust-lang.org/reference/types/textual.html
     unsafe_impl!(char: FromZeroes, AsBytes);
 }
 safety_comment! {
     /// SAFETY:
-    /// TODO(#429): Add quotes
-    /// - `FromZeroes`, `AsBytes`, `Unaligned`: Per the reference [1], `str` has
-    ///   the same layout as `[u8]`, and `[u8]` is `FromZeroes`, `AsBytes`, and
-    ///   `Unaligned`.
+    /// - `FromZeroes`, `AsBytes`, `Unaligned`: Per the reference [1], `str`
+    ///   has the same layout as `[u8]`, and `[u8]` is `FromZeroes`, `AsBytes`,
+    ///   and `Unaligned`.
     ///
     /// Note that we don't `assert_unaligned!(str)` because `assert_unaligned!`
     /// uses `align_of`, which only works for `Sized` types.
     ///
+    /// TODO(#429): Add quotes from documentation.
+    ///
     /// [1] https://doc.rust-lang.org/reference/type-layout.html#str-layout
     unsafe_impl!(str: FromZeroes, AsBytes, Unaligned);
 }
@@ -1381,7 +1385,6 @@ safety_comment! {
     // `NonZeroXxx` is `AsBytes`, but not `FromZeroes` or `FromBytes`.
     //
     /// SAFETY:
-    /// TODO(#429): Add quotes
     /// - `AsBytes`: `NonZeroXxx` has the same layout as its associated
     ///    primitive. Since it is the same size, this guarantees it has no
     ///    padding - integers have no padding, and there's no room for padding
@@ -1396,6 +1399,8 @@ safety_comment! {
     ///   be 0 bytes, which means that they must be 1 byte. The only valid
     ///   alignment for a 1-byte type is 1.
     ///
+    /// TODO(#429): Add quotes from documentation.
+    ///
     /// [1] https://doc.rust-lang.org/stable/std/num/struct.NonZeroU8.html
     /// [2] https://doc.rust-lang.org/stable/std/num/struct.NonZeroI8.html
     /// TODO(https://github.com/rust-lang/rust/pull/104082): Cite documentation
@@ -1416,7 +1421,6 @@ safety_comment! {
 }
 safety_comment! {
     /// SAFETY:
-    /// TODO(#429): Add quotes
     /// - `FromZeroes`, `FromBytes`, `AsBytes`: The Rust compiler reuses `0`
     ///   value to represent `None`, so `size_of::<Option<NonZeroXxx>>() ==
     ///   size_of::<xxx>()`; see `NonZeroXxx` documentation.
@@ -1427,6 +1431,8 @@ safety_comment! {
     ///   unthinkable that that would ever change. The only valid alignment for
     ///   a 1-byte type is 1.
     ///
+    /// TODO(#429): Add quotes from documentation.
+    ///
     /// [1] https://doc.rust-lang.org/stable/std/num/struct.NonZeroU8.html
     /// [2] https://doc.rust-lang.org/stable/std/num/struct.NonZeroI8.html
     ///
@@ -1470,14 +1476,16 @@ safety_comment! {
 }
 safety_comment! {
     /// SAFETY:
-    /// TODO(#429): Add quotes
     /// `Wrapping<T>` is guaranteed by its docs [1] to have the same layout as
     /// `T`. Also, `Wrapping<T>` is `#[repr(transparent)]`, and has a single
     /// field, which is `pub`. Per the reference [2], this means that the
     /// `#[repr(transparent)]` attribute is "considered part of the public ABI".
     ///
-    ///  references nightly?:
+    /// TODO(#429): Add quotes from documentation.
+    ///
     /// [1] TODO(https://doc.rust-lang.org/nightly/core/num/struct.Wrapping.html#layout-1):
+    /// Reference this documentation once it's available on stable.
+    ///
     /// [2] https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent
     unsafe_impl!(T: FromZeroes => FromZeroes for Wrapping<T>);
     unsafe_impl!(T: FromBytes => FromBytes for Wrapping<T>);
@@ -1496,8 +1504,8 @@ safety_comment! {
     ///   Thus, we require `T: FromZeroes` and `T: FromBytes` in order to ensure
     ///   that `T` - and thus `MaybeUninit<T>` - contains to `UnsafeCell`s.
     ///   Thus, requiring that `T` implement each of these traits is sufficient
-    /// - `Unaligned`: "MaybeUninit<T> is guaranteed to have the same size, alignment,
-    ///    and ABI as T" [1]
+    /// - `Unaligned`: "MaybeUninit<T> is guaranteed to have the same size,
+    ///    alignment, and ABI as T" [1]
     ///
     /// [1] https://doc.rust-lang.org/stable/core/mem/union.MaybeUninit.html#layout-1
     ///
@@ -1512,7 +1520,6 @@ safety_comment! {
 }
 safety_comment! {
     /// SAFETY:
-    // TODO(#429): Add reference to docs + quotes
     /// `ManuallyDrop` has the same layout as `T`, and accessing the inner value
     /// is safe (meaning that it's unsound to leave the inner value
     /// uninitialized while exposing the `ManuallyDrop` to safe code).
@@ -1528,6 +1535,7 @@ safety_comment! {
     ///   code can only ever access a `ManuallyDrop` with all initialized bytes.
     /// - `Unaligned`: `ManuallyDrop` has the same layout (and thus alignment)
     ///   as `T`, and `T: Unaligned` guarantees that that alignment is 1.
+    /// TODO(#429): Add references to docs and quotes.
     unsafe_impl!(T: ?Sized + FromZeroes => FromZeroes for ManuallyDrop<T>);
     unsafe_impl!(T: ?Sized + FromBytes => FromBytes for ManuallyDrop<T>);
     unsafe_impl!(T: ?Sized + AsBytes => AsBytes for ManuallyDrop<T>);