improve Commands doc comment (#4490)

# Objective

- The current API docs of `Commands` is very short and is very opaque to newcomers.

## Solution

- Try to explain what it is without requiring knowledge of other parts of `bevy_ecs` like `World` or `SystemParam`.


Co-authored-by: Charles <IceSentry@users.noreply.github.com>
This commit is contained in:
Charles 2022-04-17 18:17:49 +00:00
parent 639fec20d6
commit afbce46ade

View File

@ -17,13 +17,19 @@ pub trait Command: Send + Sync + 'static {
fn write(self, world: &mut World); fn write(self, world: &mut World);
} }
/// A list of commands that modify a [`World`], running at the end of the stage where they /// A list of commands that runs at the end of the stage of the system that called them.
/// have been invoked. ///
/// Commands are executed one at a time in an exclusive fashion.
//// Each command can be used to modify the [`World`] in arbitrary ways:
/// * spawning or despawning entities
/// * inserting components on new or existing entities
/// * inserting resources
/// * etc.
/// ///
/// # Usage /// # Usage
/// ///
/// `Commands` is a [`SystemParam`](crate::system::SystemParam), therefore it is declared /// Add `mut commands: Commands` as a function argument to your system to get a copy of this struct that will be applied at the end of the current stage.
/// as a function parameter: /// Commands are almost always used as a [`SystemParam`](crate::system::SystemParam).
/// ///
/// ``` /// ```
/// # use bevy_ecs::prelude::*; /// # use bevy_ecs::prelude::*;
@ -33,7 +39,8 @@ pub trait Command: Send + Sync + 'static {
/// } /// }
/// ``` /// ```
/// ///
/// Then, commands can be invoked by calling the methods of `commands`. /// Each command is implemented as a separate method.
/// Check the [`Command`] trait for a list of available commands (or implement your own!).
pub struct Commands<'w, 's> { pub struct Commands<'w, 's> {
queue: &'s mut CommandQueue, queue: &'s mut CommandQueue,
entities: &'w Entities, entities: &'w Entities,