From f10667ea4dbd1a8d7802c1bbf09ba3d23bc81b08 Mon Sep 17 00:00:00 2001
From: Jack Wrenn <jack@wrenn.fyi>
Date: Thu, 6 Feb 2025 16:44:06 +0000
Subject: [PATCH] Improve consistency of `derive(Byte*)` documentation

This edit brings the structure of these docs in line with that
used for our other derives.
---
 src/lib.rs | 73 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 58 insertions(+), 15 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index f79ecf6b3b..b30d685c8d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2838,8 +2838,7 @@ unsafe fn try_read_from<S, T: TryFromBytes>(
     Ok(unsafe { candidate.assume_init() })
 }
 
-/// Types for which a sequence of bytes all set to zero represents a valid
-/// instance of the type.
+/// Types for which a sequence of `0` bytes is a valid instance.
 ///
 /// Any memory region of the appropriate length which is guaranteed to contain
 /// only zero bytes can be viewed as any `FromZeros` type with no runtime
@@ -5443,14 +5442,36 @@ pub unsafe trait Unaligned {
         Self: Sized;
 }
 
-/// Derives an optimized implementation of [`Hash`] for types that implement
-/// [`IntoBytes`] and [`Immutable`].
+/// Derives an optimized [`Hash`] implementation.
 ///
-/// The standard library's derive for `Hash` generates a recursive descent
-/// into the fields of the type it is applied to. Instead, the implementation
-/// derived by this macro makes a single call to [`Hasher::write()`] for both
-/// [`Hash::hash()`] and [`Hash::hash_slice()`], feeding the hasher the bytes
-/// of the type or slice all at once.
+/// This derive can be applied to structs and enums implementing both
+/// [`Immutable`] and [`IntoBytes`]; e.g.:
+///
+/// ```
+/// # use zerocopy_derive::{ByteHash, Immutable, IntoBytes};
+/// #[derive(ByteHash, Immutable, IntoBytes)]
+/// #[repr(C)]
+/// struct MyStruct {
+/// # /*
+///     ...
+/// # */
+/// }
+///
+/// #[derive(ByteHash, Immutable, IntoBytes)]
+/// #[repr(u8)]
+/// enum MyEnum {
+/// #   Variant,
+/// # /*
+///     ...
+/// # */
+/// }
+/// ```
+///
+/// The standard library's [`derive(Hash)`][derive@Hash] produces hashes by
+/// individually hashing each field and combining the results. Instead, the
+/// implementations of [`Hash::hash()`] and [`Hash::hash_slice()`] generated by
+/// `derive(ByteHash)` convert the entirey of `self` to a byte slice and hashes
+/// it in a single call to [`Hasher::write()`].
 ///
 /// [`Hash`]: core::hash::Hash
 /// [`Hash::hash()`]: core::hash::Hash::hash()
@@ -5459,13 +5480,35 @@ pub unsafe trait Unaligned {
 #[cfg_attr(doc_cfg, doc(cfg(feature = "derive")))]
 pub use zerocopy_derive::ByteHash;
 
-/// Derives an optimized implementation of [`PartialEq`] and [`Eq`] for types
-/// that implement [`IntoBytes`] and [`Immutable`].
+/// Derives optimized [`PartialEq`] and [`Eq`] implementations.
+///
+/// This derive can be applied to structs and enums implementing both
+/// [`Immutable`] and [`IntoBytes`]; e.g.:
+///
+/// ```
+/// # use zerocopy_derive::{ByteEq, Immutable, IntoBytes};
+/// #[derive(ByteEq, Immutable, IntoBytes)]
+/// #[repr(C)]
+/// struct MyStruct {
+/// # /*
+///     ...
+/// # */
+/// }
+///
+/// #[derive(ByteEq, Immutable, IntoBytes)]
+/// #[repr(u8)]
+/// enum MyEnum {
+/// #   Variant,
+/// # /*
+///     ...
+/// # */
+/// }
+/// ```
 ///
-/// The standard library's derive for [`PartialEq`] generates a recursive
-/// descent into the fields of the type it is applied to. Instead, the
-/// implementation derived by this macro performs a single slice comparison of
-/// the bytes of the two values being compared.
+/// The standard library's [`derive(Eq, PartialEq)`][derive@PartialEq] computes
+/// equality by individually comparing each field. Instead, the implementation
+/// of [`PartialEq::eq`] emitted by `derive(ByteHash)` converts the entirey of
+/// `self` and `other` to byte slices and compares those slices for equality.
 #[cfg(any(feature = "derive", test))]
 #[cfg_attr(doc_cfg, doc(cfg(feature = "derive")))]
 pub use zerocopy_derive::ByteEq;