Docs and trigger_hooks cleanup

Author: james7132

crates/bevy_ecs/src/bundle.rs

@@ -637,26 +637,31 @@ impl<'w> BundleInserter<'w> {
         location: EntityLocation,
         bundle: T,
     ) -> EntityLocation {
-        /// # Safety
-        /// Must
-        unsafe fn trigger_hooks(
+        #[inline]
+        fn trigger_hooks(
             entity: Entity,
             bundle_info: &BundleInfo,
             add_bundle: &AddBundle,
             archetype: &Archetype,
             mut world: DeferredWorld,
         ) {
             if archetype.has_on_add() {
-                world.trigger_on_add(
-                    entity,
-                    bundle_info
-                        .iter_components()
-                        .zip(add_bundle.bundle_status.iter())
-                        .filter(|(_, &status)| status == ComponentStatus::Added)
-                        .map(|(id, _)| id),
-                );
+                // SAFETY: All components in the bundle are guarenteed to exist in the World
+                // as they must be initialized before creating the BundleInfo.
+                unsafe {
+                    world.trigger_on_add(
+                        entity,
+                        bundle_info
+                            .iter_components()
+                            .zip(add_bundle.bundle_status.iter())
+                            .filter(|(_, &status)| status == ComponentStatus::Added)
+                            .map(|(id, _)| id),
+                    );
+                }
             }
             if archetype.has_on_insert() {
+                // SAFETY: All components in the bundle are guarenteed to exist in the World
+                // as they must be initialized before creating the BundleInfo.
                 unsafe { world.trigger_on_insert(entity, bundle_info.iter_components()) }
             }
         }
@@ -686,15 +691,8 @@ impl<'w> BundleInserter<'w> {
                     );
                 }
                 // SAFETY: We have no outstanding mutable references to world as they were dropped
-                unsafe {
-                    trigger_hooks(
-                        entity,
-                        bundle_info,
-                        add_bundle,
-                        archetype,
-                        self.world.into_deferred(),
-                    );
-                }
+                let deferred_world = unsafe { self.world.into_deferred() };
+                trigger_hooks(entity, bundle_info, add_bundle, archetype, deferred_world);
                 location
             }
             InsertBundleResult::NewArchetypeSameTable { new_archetype } => {
@@ -737,15 +735,8 @@ impl<'w> BundleInserter<'w> {
                 };
 
                 // SAFETY: We have no outstanding mutable references to world as they were dropped
-                unsafe {
-                    trigger_hooks(
-                        entity,
-                        bundle_info,
-                        add_bundle,
-                        archetype,
-                        self.world.into_deferred(),
-                    );
-                }
+                let deferred_world = unsafe { self.world.into_deferred() };
+                trigger_hooks(entity, bundle_info, add_bundle, archetype, deferred_world);
 
                 new_location
             }
@@ -839,15 +830,8 @@ impl<'w> BundleInserter<'w> {
                 };
 
                 // SAFETY: We have no outstanding mutable references to world as they were dropped
-                unsafe {
-                    trigger_hooks(
-                        entity,
-                        bundle_info,
-                        add_bundle,
-                        archetype,
-                        self.world.into_deferred(),
-                    );
-                }
+                let deferred_world = unsafe { self.world.into_deferred() };
+                trigger_hooks(entity, bundle_info, add_bundle, archetype, deferred_world);
 
                 new_location
             }

crates/bevy_ptr/src/lib.rs

@@ -33,8 +33,45 @@ mod sealed {
 pub struct ConstNonNull<T: ?Sized>(NonNull<T>);
 
 impl<T: ?Sized> ConstNonNull<T> {
+    /// Returns a shared reference to the value.
+    ///
+    /// # Safety
+    ///
+    /// When calling this method, you have to ensure that all of the following is true:
+    ///
+    /// * The pointer must be properly aligned.
+    ///
+    /// * It must be "dereferenceable" in the sense defined in [the module documentation].
+    ///
+    /// * The pointer must point to an initialized instance of `T`.
+    ///
+    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
+    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
+    ///   In particular, while this reference exists, the memory the pointer points to must
+    ///   not get mutated (except inside `UnsafeCell`).
+    ///
+    /// This applies even if the result of this method is unused!
+    /// (The part about being initialized is not yet fully decided, but until
+    /// it is, the only safe approach is to ensure that they are indeed initialized.)
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ptr::NonNull;
+    ///
+    /// let mut x = 0u32;
+    /// let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");
+    ///
+    /// let ref_x = unsafe { ptr.as_ref() };
+    /// println!("{ref_x}");
+    /// ```
+    ///
+    /// [the module documentation]: core::ptr#safety
+    #[inline]
     pub unsafe fn as_ref<'a>(&self) -> &'a T {
-        self.0.as_ref()
+        // SAFETY: This function's safety invariants are identical to `NonNull::as_ref`
+        // The caller must satsify all of them.
+        unsafe { self.0.as_ref() }
     }
 }