From 28039ce7eb29265c35cf721cbee0bdf1b13fd786 Mon Sep 17 00:00:00 2001
From: Jack Wrenn <jack@wrenn.fyi>
Date: Fri, 15 Mar 2024 16:07:07 +0000
Subject: [PATCH] Use pseudocode to document `transmute_ref`

Partially addresses #1046.
---
 src/lib.rs | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 2e74ae2390..3c9e62a916 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4418,14 +4418,27 @@ macro_rules! transmute {
 /// Safely transmutes a mutable or immutable reference of one type to an
 /// immutable reference of another type of the same size.
 ///
-/// The expression `$e` must have a concrete type, `&T` or `&mut T`, where `T:
-/// Sized + IntoBytes`. The `transmute_ref!` expression must also have a
-/// concrete type, `&U` (`U` is inferred from the calling context), where `U:
-/// Sized + FromBytes`. It must be the case that `align_of::<T>() >=
-/// align_of::<U>()`.
+/// This macro behaves like an invocation of this function:
+///
+/// ```ignore
+/// const fn transmute_ref<'src, 'dst, Src, Dst>(src: &'src Src) -> &'dst Dst
+/// where
+///     'src: 'dst,
+///     Src: IntoBytes + NoCell,
+///     Dst: FromBytes + NoCell,
+///     size_of::<Src>() == size_of::<Dst>(),
+///     align_of::<Src>() >= align_of::<Dst>(),
+/// {
+/// # /*
+///     ...
+/// # */
+/// }
+/// ```
 ///
-/// The lifetime of the input type, `&T` or `&mut T`, must be the same as or
-/// outlive the lifetime of the output type, `&U`.
+/// However, unlike a function, this macro can only be invoked when the types of
+/// `Src` and `Dst` are completely concrete. The types `Src` and `Dst` are
+/// inferred from the calling context; they cannot be explicitly specified in
+/// the macro invocation.
 ///
 /// # Examples
 ///