Improve transmute docs

library/core/src/intrinsics.rs

@@ -1223,6 +1223,35 @@ extern "rust-intrinsic" {
     /// }
     /// ```
     ///
+    /// However, since pointers (and references) have provenance and integers do not, the following
+    /// program executes UB:
+    /// ```no_run
+    /// let ptr: *const u8 = &0;
+    /// let address = unsafe {
+    ///     std::mem::transmute::<*const u8, usize>(ptr)
+    /// };
+    /// let new_ptr = unsafe {
+    ///     std::mem::transmute::<usize, *const u8>(address)
+    /// };
+    /// unsafe {
+    ///     assert_eq!(*ptr, 0);
+    /// }
+    /// ```
+    /// And this program does as well:
+    /// ```no_run
+    /// let ptr: *const u8 = &0;
+    /// let address = unsafe {
+    ///     std::mem::transmute::<*const u8, usize>(ptr)
+    /// };
+    /// let new_ref = unsafe {
+    ///     std::mem::transmute::<usize, &u8>(address)
+    /// };
+    /// ```
+    /// Distinguishing exactly which operation in this program is invalid touches on unspecified
+    /// aspects of the Rust memory model. If you need to store a pointer as another type then
+    /// recover the original pointer later, you cannot use `transmute` to round-trip through a
+    /// type which is not a pointer, reference, or [`MaybeUninit`][crate::mem::MaybeUninit].
+    ///
     /// # Alternatives
     ///
     /// Don't despair: many uses of `transmute` can be achieved through other means.