Skip to content

Commit afbce46

Browse files
committed
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 <[email protected]>
1 parent 639fec2 commit afbce46

File tree

1 file changed

+12
-5
lines changed
  • crates/bevy_ecs/src/system/commands

1 file changed

+12
-5
lines changed

crates/bevy_ecs/src/system/commands/mod.rs

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,19 @@ pub trait Command: Send + Sync + 'static {
1717
fn write(self, world: &mut World);
1818
}
1919

20-
/// A list of commands that modify a [`World`], running at the end of the stage where they
21-
/// have been invoked.
20+
/// A list of commands that runs at the end of the stage of the system that called them.
21+
///
22+
/// Commands are executed one at a time in an exclusive fashion.
23+
//// Each command can be used to modify the [`World`] in arbitrary ways:
24+
/// * spawning or despawning entities
25+
/// * inserting components on new or existing entities
26+
/// * inserting resources
27+
/// * etc.
2228
///
2329
/// # Usage
2430
///
25-
/// `Commands` is a [`SystemParam`](crate::system::SystemParam), therefore it is declared
26-
/// as a function parameter:
31+
/// 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.
32+
/// Commands are almost always used as a [`SystemParam`](crate::system::SystemParam).
2733
///
2834
/// ```
2935
/// # use bevy_ecs::prelude::*;
@@ -33,7 +39,8 @@ pub trait Command: Send + Sync + 'static {
3339
/// }
3440
/// ```
3541
///
36-
/// Then, commands can be invoked by calling the methods of `commands`.
42+
/// Each command is implemented as a separate method.
43+
/// Check the [`Command`] trait for a list of available commands (or implement your own!).
3744
pub struct Commands<'w, 's> {
3845
queue: &'s mut CommandQueue,
3946
entities: &'w Entities,

0 commit comments

Comments
 (0)