Better safety documentation

Author: MrGVSV

crates/bevy_reflect/bevy_reflect_derive/src/enum_utility.rs

@@ -69,6 +69,7 @@ pub(crate) fn get_variant_constructors(
                 if let Some(field_ty) = &field.attrs.remote {
                     quote! {
                         unsafe {
+                            // SAFE: The wrapper type should be repr(transparent) over the remote type
                             ::std::mem::transmute(
                                 <#field_ty as #bevy_reflect_path::FromReflect>::from_reflect(#ref_value #accessor)
                                 #unwrapper

crates/bevy_reflect/bevy_reflect_derive/src/impls/enums.rs

@@ -380,6 +380,7 @@ fn generate_impls(reflect_enum: &ReflectEnum, ref_index: &Ident, ref_name: &Iden
                 .as_ref()
                 .map(|ty| {
                     quote! {
+                        // SAFE: The wrapper type should be repr(transparent) over the remote type
                         unsafe { ::core::mem::transmute::<#ref_token _, #ref_token #ty>(#ident) }
                     }
                 })

crates/bevy_reflect/bevy_reflect_derive/src/lib.rs

@@ -100,7 +100,7 @@ pub fn reflect_trait(args: TokenStream, input: TokenStream) -> TokenStream {
 /// Generates a wrapper type that can be used to "derive `Reflect`" for remote types.
 ///
 /// This works by wrapping the remote type in a generated wrapper that has the `#[repr(transparent)]` attribute.
-/// This allows the two types to be safely transmuted back-and-forth.
+/// This allows the two types to be safely [transmuted] back-and-forth.
 ///
 /// # Defining the Wrapper
 ///
@@ -156,6 +156,26 @@ pub fn reflect_trait(args: TokenStream, input: TokenStream) -> TokenStream {
 /// pub struct Wrapper<T: Default + Clone>(RemoteType<T>);
 /// ```
 ///
+/// # Usage as a Field
+///
+/// You can tell `Reflect` to use a remote type's wrapper internally on fields of a struct or enum.
+/// This allows the real type to be used as usual while `Reflect` handles everything internally.
+/// To do this, add the `#[reflect(remote = "...")]` attribute to your field:
+///
+/// ```ignore
+/// #[derive(Reflect)]
+/// struct SomeStruct {
+///   #[reflect(remote = "RemoteTypeWrapper")]
+///   data: RemoteType
+/// }
+/// ```
+///
+/// ## Safety
+///
+/// When using the `#[reflect(remote = "...")]` field attribute, be sure you are defining the correct wrapper type.
+/// Internally, this field will be unsafely [transmuted], and is only sound if using a wrapper generated for the remote type.
+/// This also means keeping your wrapper definitions up-to-date with the remote types.
+///
 /// # `FromReflect`
 ///
 /// Because of the way this code modifies the item it's defined on, it is not possible to implement `FromReflect`
@@ -172,6 +192,7 @@ pub fn reflect_trait(args: TokenStream, input: TokenStream) -> TokenStream {
 /// This is the _only_ trait this works with. You cannot derive any other traits using this method.
 /// For those, use regular derive macros below this one.
 ///
+/// [transmuted]: std::mem::transmute
 #[proc_macro_attribute]
 pub fn reflect_remote(args: TokenStream, input: TokenStream) -> TokenStream {
     remote::reflect_remote(args, input)

crates/bevy_reflect/bevy_reflect_derive/src/struct_utility.rs

@@ -27,6 +27,7 @@ impl FieldAccessors {
             match &field.attrs.remote {
                 Some(wrapper_ty) => {
                     quote! {
+                        // SAFE: The wrapper type should be repr(transparent) over the remote type
                         unsafe { ::core::mem::transmute_copy::<_, #wrapper_ty>(&#accessor) }
                     }
                 }
@@ -37,6 +38,7 @@ impl FieldAccessors {
             match &field.attrs.remote {
                 Some(wrapper_ty) => {
                     quote! {
+                        // SAFE: The wrapper type should be repr(transparent) over the remote type
                         unsafe { ::core::mem::transmute::<&_, &#wrapper_ty>(&#accessor) }
                     }
                 }
@@ -47,6 +49,7 @@ impl FieldAccessors {
             match &field.attrs.remote {
                 Some(wrapper_ty) => {
                     quote! {
+                        // SAFE: The wrapper type should be repr(transparent) over the remote type
                         unsafe { ::core::mem::transmute::<&mut _, &mut #wrapper_ty>(&mut #accessor) }
                     }
                 }