Add a doc note about despawn footgun

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

@@ -860,6 +860,12 @@ 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, which will leave the
+    /// hierarchy in an invalid state if the entity has a parent or any children. You can use
+    /// `despawn_recursive` or `despawn_descendants` instead to preserve the hierarchy.
+    ///
     /// # Panics
     ///
     /// The command will panic when applied if the associated entity does not exist.
@@ -1062,6 +1068,12 @@ 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, which will leave the
+/// hierarchy in an invalid state if the entity has a parent or any children. You can use
+/// `DespawnRecursive` or `DespawnDescendants` instead to preserve the hierarchy.
 #[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, which will leave the
+    /// hierarchy in an invalid state if the entity has a parent or any children.
+    ///
     /// ```
     /// use bevy_ecs::{component::Component, world::World};
     ///