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.
This commit is contained in:
Dokkae 2024-09-28 21:13:27 +02:00 committed by GitHub
parent 7ee5143d45
commit 29edad4690
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 14 additions and 5 deletions

View File

@ -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
///
/// ```

View File

@ -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.
///

View File

@ -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};