[macros] Clarify size/align behavior of try macros (#2975)

Clarify that, while `try_transmute_{ref,mut}!` check referent validity
at runtime, they enforce size and alignment compatibility at compile
time.

Release 0.8.38.

gherrit-pr-id: G2712a29a4b58bdb5d76d4b15763a15f8e8824ae0

Author: joshlf

Cargo.lock

@@ -15,7 +15,7 @@
 [package]
 edition = "2021"
 name = "zerocopy"
-version = "0.8.37"
+version = "0.8.38"
 authors = [
     "Joshua Liebow-Feeser <joshlf@google.com>",
     "Jack Wrenn <jswrenn@amazon.com>",
@@ -112,13 +112,13 @@ __internal_use_only_features_that_work_on_stable = [
 ]
 
 [dependencies]
-zerocopy-derive = { version = "=0.8.37", path = "zerocopy-derive", optional = true }
+zerocopy-derive = { version = "=0.8.38", path = "zerocopy-derive", optional = true }
 
 # The "associated proc macro pattern" ensures that the versions of zerocopy and
 # zerocopy-derive remain equal, even if the 'derive' feature isn't used.
 # See: https://github.com/matklad/macro-dep-test
 [target.'cfg(any())'.dependencies]
-zerocopy-derive = { version = "=0.8.37", path = "zerocopy-derive" }
+zerocopy-derive = { version = "=0.8.38", path = "zerocopy-derive" }
 
 [dev-dependencies]
 # FIXME(#381) Remove this dependency once we have our own layout gadgets.
@@ -134,4 +134,4 @@ testutil = { path = "testutil" }
 # CI test failures.
 trybuild = { version = "=1.0.89", features = ["diff"] }
 # In tests, unlike in production, zerocopy-derive is not optional
-zerocopy-derive = { version = "=0.8.37", path = "zerocopy-derive" }
+zerocopy-derive = { version = "=0.8.38", path = "zerocopy-derive" }

Cargo.toml

@@ -623,6 +623,11 @@ macro_rules! try_transmute {
 /// immutable reference of another type of the same size and compatible
 /// alignment.
 ///
+/// *Note that while the **value** of the referent is checked for validity at
+/// runtime, the **size** and **alignment** are checked at compile time. For
+/// conversions which are fallible with respect to size and alignment, see the
+/// methods on [`TryFromBytes`].*
+///
 /// This macro behaves like an invocation of this function:
 ///
 /// ```ignore
@@ -642,6 +647,8 @@ macro_rules! try_transmute {
 /// The types `Src` and `Dst` are inferred from the calling context; they cannot
 /// be explicitly specified in the macro invocation.
 ///
+/// [`TryFromBytes`]: crate::TryFromBytes
+///
 /// # Size compatibility
 ///
 /// `try_transmute_ref!` supports transmuting between `Sized` types, between
@@ -744,6 +751,11 @@ macro_rules! try_transmute_ref {
 /// Conditionally transmutes a mutable reference of one type to a mutable
 /// reference of another type of the same size and compatible alignment.
 ///
+/// *Note that while the **value** of the referent is checked for validity at
+/// runtime, the **size** and **alignment** are checked at compile time. For
+/// conversions which are fallible with respect to size and alignment, see the
+/// methods on [`TryFromBytes`].*
+///
 /// This macro behaves like an invocation of this function:
 ///
 /// ```ignore
@@ -763,6 +775,8 @@ macro_rules! try_transmute_ref {
 /// The types `Src` and `Dst` are inferred from the calling context; they cannot
 /// be explicitly specified in the macro invocation.
 ///
+/// [`TryFromBytes`]: crate::TryFromBytes
+///
 /// # Size compatibility
 ///
 /// `try_transmute_mut!` supports transmuting between `Sized` types, between

src/macros.rs

@@ -9,7 +9,7 @@
 [package]
 edition = "2021"
 name = "zerocopy-derive"
-version = "0.8.37"
+version = "0.8.38"
 authors = ["Joshua Liebow-Feeser <joshlf@google.com>", "Jack Wrenn <jswrenn@amazon.com>"]
 description = "Custom derive for traits from the zerocopy crate"
 license = "BSD-2-Clause OR Apache-2.0 OR MIT"