From 6a15ed564df9fc4a443780247e8f036eb27a2e45 Mon Sep 17 00:00:00 2001
From: TheBigCheese <32036861+13ros27@users.noreply.github.com>
Date: Tue, 12 Dec 2023 19:27:11 +0000
Subject: [PATCH] Improve `EntityWorldMut.remove`, `retain` and `despawn` docs
 by linking to more detail (#10943)

## Solution

`Commands.remove` and `.retain` (because I copied `remove`s doc)
referenced `EntityWorldMut.remove` and `retain` for more detail but the
`Commands` docs are much more detailed (which makes sense because it is
the most common api), so I have instead inverted this so that
`EntityWorldMut` docs link to `Commands`.

I also made `EntityWorldMut.despawn` reference `World.despawn` for more
details, like `Commands.despawn` does.
---
 crates/bevy_ecs/src/system/commands/mod.rs | 6 ------
 crates/bevy_ecs/src/world/entity_ref.rs    | 6 ++++++
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs
index 5f081804da..7b0638103e 100644
--- a/crates/bevy_ecs/src/system/commands/mod.rs
+++ b/crates/bevy_ecs/src/system/commands/mod.rs
@@ -812,9 +812,6 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> {
 
     /// Removes a [`Bundle`] of components from the entity.
     ///
-    /// See [`EntityWorldMut::remove`](EntityWorldMut::remove) for more
-    /// details.
-    ///
     /// # Example
     ///
     /// ```
@@ -912,9 +909,6 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> {
     ///
     /// This can also be used to remove all the components from the entity by passing it an empty Bundle.
     ///
-    /// See [`EntityWorldMut::retain`](EntityWorldMut::retain) for more
-    /// details.
-    ///
     /// # Example
     ///
     /// ```
diff --git a/crates/bevy_ecs/src/world/entity_ref.rs b/crates/bevy_ecs/src/world/entity_ref.rs
index 5f17409c90..586fc03246 100644
--- a/crates/bevy_ecs/src/world/entity_ref.rs
+++ b/crates/bevy_ecs/src/world/entity_ref.rs
@@ -889,6 +889,8 @@ impl<'w> EntityWorldMut<'w> {
     }
 
     /// Removes any components in the [`Bundle`] from the entity.
+    ///
+    /// See [`EntityCommands::remove`](crate::system::EntityCommands::remove) for more details.
     // TODO: BundleRemover?
     pub fn remove<T: Bundle>(&mut self) -> &mut Self {
         let archetypes = &mut self.world.archetypes;
@@ -920,6 +922,8 @@ impl<'w> EntityWorldMut<'w> {
     }
 
     /// Removes any components except those in the [`Bundle`] from the entity.
+    ///
+    /// See [`EntityCommands::retain`](crate::system::EntityCommands::retain) for more details.
     pub fn retain<T: Bundle>(&mut self) -> &mut Self {
         let archetypes = &mut self.world.archetypes;
         let storages = &mut self.world.storages;
@@ -961,6 +965,8 @@ impl<'w> EntityWorldMut<'w> {
     }
 
     /// Despawns the current entity.
+    ///
+    /// See [`World::despawn`] for more details.
     pub fn despawn(self) {
         debug!("Despawning entity {:?}", self.entity);
         let world = self.world;