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);
}
/// A list of commands that modify a [`World`], running at the end of the stage where they
/// have been invoked.
/// A list of commands that runs at the end of the stage of the system that called them.
///
/// 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
///
/// `Commands` is a [`SystemParam`](crate::system::SystemParam), therefore it is declared
/// as a function parameter:
/// 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.
/// Commands are almost always used as a [`SystemParam`](crate::system::SystemParam).
///
/// ```
/// # 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> {
queue: &'s mut CommandQueue,
entities: &'w Entities,