Improve consistency of derive(Byte*) documentation (#2306) (#2465)

This edit brings the structure of these docs in line with that
used for our other derives.

Co-authored-by: Jack Wrenn <[email protected]>

Author: google-pr-creation-bot

src/lib.rs

@@ -3250,8 +3250,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
@@ -5869,14 +5868,37 @@ 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()`]. This may have performance
+/// advantages.
 ///
 /// [`Hash`]: core::hash::Hash
 /// [`Hash::hash()`]: core::hash::Hash::hash()
@@ -5885,13 +5907,36 @@ 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.
+/// This may have performance advantages.
 #[cfg(any(feature = "derive", test))]
 #[cfg_attr(doc_cfg, doc(cfg(feature = "derive")))]
 pub use zerocopy_derive::ByteEq;