From 29edad46905d4a59b14674fc875f3858a743e31b Mon Sep 17 00:00:00 2001
From: Dokkae <90514461+Dokkae6949@users.noreply.github.com>
Date: Sat, 28 Sep 2024 21:13:27 +0200
Subject: [PATCH] Improve unclear docs about spawn(_batch) and ParallelCommands
 (#15491)

> [!NOTE]
> This is my first PR, so if something is incorrect
> or missing, please let me know :3

# Objective

- Clarifies `spawn`, `spawn_batch` and `ParallelCommands` docs about
performance and use cases
- Fixes #15472

## Solution

Add comments to `spawn`, `spawn_batch` and `ParallelCommands` to clarify
the
intended use case and link to other/better ways of doing spawning things
for
certain use cases.
---
 crates/bevy_ecs/src/system/commands/mod.rs            | 3 +++
 crates/bevy_ecs/src/system/commands/parallel_scope.rs | 7 ++++++-
 crates/bevy_ecs/src/world/mod.rs                      | 9 +++++----
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs
index 1476f32db1..fca9e8f94b 100644
--- a/crates/bevy_ecs/src/system/commands/mod.rs
+++ b/crates/bevy_ecs/src/system/commands/mod.rs
@@ -338,6 +338,9 @@ impl<'w, 's> Commands<'w, 's> {
     /// Pushes a [`Command`] to the queue for creating a new entity with the given [`Bundle`]'s components,
     /// and returns its corresponding [`EntityCommands`].
     ///
+    /// In case multiple bundles of the same [`Bundle`] type need to be spawned,
+    /// [`spawn_batch`](Self::spawn_batch) should be used for better performance.
+    ///
     /// # Example
     ///
     /// ```
diff --git a/crates/bevy_ecs/src/system/commands/parallel_scope.rs b/crates/bevy_ecs/src/system/commands/parallel_scope.rs
index 582825aa79..82a00ceac2 100644
--- a/crates/bevy_ecs/src/system/commands/parallel_scope.rs
+++ b/crates/bevy_ecs/src/system/commands/parallel_scope.rs
@@ -14,7 +14,12 @@ struct ParallelCommandQueue {
     thread_queues: Parallel<CommandQueue>,
 }
 
-/// An alternative to [`Commands`] that can be used in parallel contexts, such as those in [`Query::par_iter`](crate::system::Query::par_iter)
+/// An alternative to [`Commands`] that can be used in parallel contexts, such as those
+/// in [`Query::par_iter`](crate::system::Query::par_iter).
+///
+/// For cases where multiple non-computation-heavy (lightweight) bundles of the same
+/// [`Bundle`](crate::prelude::Bundle) type need to be spawned, consider using
+/// [`Commands::spawn_batch`] for better performance.
 ///
 /// Note: Because command application order will depend on how many threads are ran, non-commutative commands may result in non-deterministic results.
 ///
diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs
index 7e0d194442..80a05e2a18 100644
--- a/crates/bevy_ecs/src/world/mod.rs
+++ b/crates/bevy_ecs/src/world/mod.rs
@@ -921,7 +921,8 @@ impl World {
 
     /// Spawns a new [`Entity`] with a given [`Bundle`] of [components](`Component`) and returns
     /// a corresponding [`EntityWorldMut`], which can be used to add components to the entity or
-    /// retrieve its id.
+    /// retrieve its id. In case large batches of entities need to be spawned, consider using
+    /// [`World::spawn_batch`] instead.
     ///
     /// ```
     /// use bevy_ecs::{bundle::Bundle, component::Component, world::World};
@@ -1018,9 +1019,9 @@ impl World {
 
     /// Spawns a batch of entities with the same component [`Bundle`] type. Takes a given
     /// [`Bundle`] iterator and returns a corresponding [`Entity`] iterator.
-    /// This is more efficient than spawning entities and adding components to them individually,
-    /// but it is limited to spawning entities with the same [`Bundle`] type, whereas spawning
-    /// individually is more flexible.
+    /// This is more efficient than spawning entities and adding components to them individually
+    /// using [`World::spawn`], but it is limited to spawning entities with the same [`Bundle`]
+    /// type, whereas spawning individually is more flexible.
     ///
     /// ```
     /// use bevy_ecs::{component::Component, entity::Entity, world::World};