Fix safety comment citations (#2800)

* Fix safety comment citations to use pinned Rust versions

Updates safety comments in `src/impls.rs`, `src/util/mod.rs`,
`src/lib.rs`, `src/pointer/ptr.rs`, and `zerocopy-derive/src/enum.rs`
to cite specific stable Rust versions (mainly 1.81.0) instead of
generic `stable` or `nightly` URLs.

Adds quotes from the documentation to support the safety claims,
as per the issue requirements.

Resolves FIXMEs related to missing citations for `NonZero` layout,
`Option<NonZero>` compatibility, and `null` pointer representation.

Closes #1655

* Fix safety comment citations to use pinned Rust versions

Updates safety comments in `src/impls.rs`, `src/util/mod.rs`,
`src/lib.rs`, `src/pointer/ptr.rs`, and `zerocopy-derive/src/enum.rs`
to cite specific stable Rust versions (mainly 1.81.0) instead of
generic `stable` or `nightly` URLs.

Adds quotes from the documentation to support the safety claims,
as per the issue requirements.

Resolves FIXMEs related to missing citations for `NonZero` layout,
`Option<NonZero>` compatibility, and `null` pointer representation.

Clarifies safety comment in `src/pointer/ptr.rs` regarding validity
preservation when iterating over slices.

Closes #1655

* Update NonZero URLs to type alias format

Corrects the URLs for `NonZeroU8` and `NonZeroI8` documentation
to point to `type.NonZero*.html` instead of `struct.NonZero*.html`,
as they are type aliases in Rust 1.81.0.

Ensures quoted text regarding layout and Option compatibility is accurate.

* Add NPO size guarantee quote for NonZero

Adds the documentation quote "Thanks to the null pointer optimization,
NonZero... and Option<NonZero...> are guaranteed to have the same size
and alignment" to the safety comments for `Option<NonZeroU8>` and
`Option<NonZeroI8>`.

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: google-labs-jules[bot]

src/impls.rs

@@ -154,12 +154,13 @@ impl_size_eq!(char, Unalign<u32>);
 // Note that we don't `assert_unaligned!(str)` because `assert_unaligned!` uses
 // `align_of`, which only works for `Sized` types.
 //
-// FIXME(#429):
-// - Add quotes from documentation.
-// - Improve safety proof for `FromZeros` and `IntoBytes`; having the same
-//   layout as `[u8]` isn't sufficient.
+// FIXME(#429): Improve safety proof for `FromZeros` and `IntoBytes`; having the same
+// layout as `[u8]` isn't sufficient.
+//
+// [1] Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#str-layout:
 //
-// [1] https://doc.rust-lang.org/1.81.0/reference/type-layout.html#str-layout
+//   String slices are a UTF-8 representation of characters that have the same
+//   layout as slices of type `[u8]`.
 #[allow(clippy::multiple_unsafe_ops_per_block)]
 const _: () = unsafe { unsafe_impl!(str: Immutable, FromZeros, IntoBytes, Unaligned) };
 
@@ -216,15 +217,15 @@ macro_rules! unsafe_impl_try_from_bytes_for_nonzero {
 //   how we'd prove it short of adding text to the stdlib docs that says so
 //   explicitly, which likely wouldn't be accepted.
 //
-// [1] https://doc.rust-lang.org/1.81.0/std/num/type.NonZeroU8.html
+// [1] Per https://doc.rust-lang.org/1.81.0/std/num/type.NonZeroU8.html:
 //
 //     `NonZeroU8` is guaranteed to have the same layout and bit validity as `u8` with
-//     the exception that 0 is not a valid instance
+//     the exception that 0 is not a valid instance.
 //
-// [2] https://doc.rust-lang.org/1.81.0/std/num/type.NonZeroI8.html
+// [2] Per https://doc.rust-lang.org/1.81.0/std/num/type.NonZeroI8.html:
 //
-// FIXME(https://github.com/rust-lang/rust/pull/104082): Cite documentation that
-// layout is the same as primitive layout.
+//     `NonZeroI8` is guaranteed to have the same layout and bit validity as `i8` with
+//     the exception that 0 is not a valid instance.
 #[allow(clippy::multiple_unsafe_ops_per_block)]
 const _: () = unsafe {
     unsafe_impl!(NonZeroU8: Immutable, IntoBytes, Unaligned);
@@ -267,13 +268,19 @@ const _: () = unsafe {
 //   purpose of those types, it's virtually unthinkable that that would ever
 //   change. The only valid alignment for a 1-byte type is 1.
 //
-// FIXME(#429): Add quotes from documentation.
+// [1] Per https://doc.rust-lang.org/1.81.0/std/num/type.NonZeroU8.html:
+//
+//     `Option<NonZeroU8>` is guaranteed to be compatible with `u8`, including in FFI.
+//
+//     Thanks to the null pointer optimization, `NonZeroU8` and `Option<NonZeroU8>`
+//     are guaranteed to have the same size and alignment:
 //
-// [1] https://doc.rust-lang.org/stable/std/num/struct.NonZeroU8.html
-// [2] https://doc.rust-lang.org/stable/std/num/struct.NonZeroI8.html
+// [2] Per https://doc.rust-lang.org/1.81.0/std/num/type.NonZeroI8.html:
 //
-// FIXME(https://github.com/rust-lang/rust/pull/104082): Cite documentation for
-// layout guarantees.
+//     `Option<NonZeroI8>` is guaranteed to be compatible with `i8`, including in FFI.
+//
+//     Thanks to the null pointer optimization, `NonZeroI8` and `Option<NonZeroI8>`
+//     are guaranteed to have the same size and alignment:
 #[allow(clippy::multiple_unsafe_ops_per_block)]
 const _: () = unsafe {
     unsafe_impl!(Option<NonZeroU8>: TryFromBytes, FromZeros, FromBytes, IntoBytes, Unaligned);
@@ -780,7 +787,7 @@ impl_for_transmute_from!(T: ?Sized + IntoBytes => IntoBytes for ManuallyDrop<T>[
 // SAFETY: `ManuallyDrop<T>` has the same layout as `T` [1], and thus has the
 // same alignment as `T`.
 //
-// [1] Per https://doc.rust-lang.org/nightly/core/mem/struct.ManuallyDrop.html:
+// [1] Per https://doc.rust-lang.org/1.81.0/std/mem/struct.ManuallyDrop.html:
 //
 //   `ManuallyDrop<T>` is guaranteed to have the same layout and bit validity as
 //   `T`
@@ -928,8 +935,14 @@ const _: () = unsafe {
 // `IntoBytes` for raw pointers eventually, but we are holding off until we can
 // figure out how to address those footguns.
 //
-// [1] FIXME(https://github.com/rust-lang/rust/pull/116988): Cite the
-// documentation once this PR lands.
+// [1] Per https://doc.rust-lang.org/1.81.0/std/ptr/fn.null.html:
+//
+//   Creates a null raw pointer.
+//
+//   This function is equivalent to zero-initializing the pointer:
+//   `MaybeUninit::<*const T>::zeroed().assume_init()`.
+//
+//   The resulting pointer has the address 0.
 #[allow(clippy::multiple_unsafe_ops_per_block)]
 const _: () = unsafe {
     unsafe_impl!(T: ?Sized => Immutable for *const T);

src/lib.rs

@@ -3158,7 +3158,7 @@ pub unsafe trait FromZeros: TryFromBytes {
             // is sufficiently aligned. Since the produced pointer is a
             // `NonNull`, it is non-null.
             //
-            // [1] Per https://doc.rust-lang.org/nightly/std/boxed/index.html#memory-layout:
+            // [1] Per https://doc.rust-lang.org/1.81.0/std/boxed/index.html#memory-layout:
             //
             //   For zero-sized values, the `Box` pointer has to be non-null and sufficiently aligned.
             //

src/pointer/ptr.rs

@@ -1225,8 +1225,17 @@ mod _project {
             // 1. `elem`, conditionally, conforms to the validity invariant of
             //    `I::Alignment`. If `elem` is projected from data well-aligned
             //    for `[T]`, `elem` will be valid for `T`.
-            // 2. FIXME: Need to cite facts about `[T]`'s layout (same for the
-            //    preceding points)
+            // 2. `elem` conforms to the validity invariant of `I::Validity`.
+            //    Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#array-layout:
+            //
+            //      Slices have the same layout as the section of the array they
+            //      slice.
+            //
+            //    Arrays are laid out so that the zero-based `nth` element of
+            //    the array is offset from the start of the array by `n *
+            //    size_of::<T>()` bytes. Thus, `elem` addresses a valid `T`
+            //    within the slice. Since `self` satisfies `I::Validity`, `elem`
+            //    also satisfies `I::Validity`.
             self.as_inner().iter().map(|elem| unsafe { Ptr::from_inner(elem) })
         }
     }

src/util/mod.rs

@@ -372,7 +372,7 @@ where
         // check ensures their shared safety precondition: that the supplied
         // layout is not zero-sized type [1].
         //
-        // [1] Per https://doc.rust-lang.org/stable/std/alloc/trait.GlobalAlloc.html#tymethod.alloc:
+        // [1] Per https://doc.rust-lang.org/1.81.0/std/alloc/trait.GlobalAlloc.html#tymethod.alloc:
         //
         //     This function is unsafe because undefined behavior can result if
         //     the caller does not ensure that layout has non-zero size.

zerocopy-derive/src/enum.rs

@@ -71,8 +71,14 @@ fn generate_tag_consts(data: &DataEnum) -> TokenStream {
             // Because these are the same size, this is defined to be a no-op
             // and therefore is a lossless conversion [2].
             //
-            // [1]: https://doc.rust-lang.org/stable/reference/expressions/operator-expr.html#enum-cast
-            // [2]: https://doc.rust-lang.org/stable/reference/expressions/operator-expr.html#numeric-cast
+            // [1] Per https://doc.rust-lang.org/1.81.0/reference/expressions/operator-expr.html#enum-cast:
+            //
+            //   Casts an enum to its discriminant.
+            //
+            // [2] Per https://doc.rust-lang.org/1.81.0/reference/expressions/operator-expr.html#numeric-cast:
+            //
+            //   Casting between two integers of the same size (e.g. i32 -> u32)
+            //   is a no-op.
             #[allow(non_upper_case_globals)]
             const #tag_ident: ___ZerocopyTagPrimitive =
                 ___ZerocopyTag::#variant_ident as ___ZerocopyTagPrimitive;