Add a doc note about despawn footgun

crates/bevy_ecs/src/system/commands/mod.rs

@@ -860,6 +860,11 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> {
     ///
     /// See [`World::despawn`] for more details.
     ///
+    /// # Note
+    ///
+    /// This won't clean up external references to the entity (such as parent-child relationships
+    /// if you're using `bevy_hierarchy`), which may leave the world in an invalid state.
+    ///
     /// # Panics
     ///
     /// The command will panic when applied if the associated entity does not exist.
@@ -1062,6 +1067,11 @@ where
 
 /// A [`Command`] that despawns a specific entity.
 /// This will emit a warning if the entity does not exist.
+///
+/// # Note
+///
+/// This won't clean up external references to the entity (such as parent-child relationships
+/// if you're using `bevy_hierarchy`), which may leave the world in an invalid state.
 #[derive(Debug)]
 pub struct Despawn {
     /// The entity that will be despawned.

crates/bevy_ecs/src/world/mod.rs

@@ -852,6 +852,12 @@ impl World {
     /// Despawns the given `entity`, if it exists. This will also remove all of the entity's
     /// [`Component`]s. Returns `true` if the `entity` is successfully despawned and `false` if
     /// the `entity` does not exist.
+    ///
+    /// # Note
+    ///
+    /// This won't clean up external references to the entity (such as parent-child relationships
+    /// if you're using `bevy_hierarchy`), which may leave the world in an invalid state.
+    ///
     /// ```
     /// use bevy_ecs::{component::Component, world::World};
     ///