Clarify Commands API docs (#5938)

# Objective

- Make people stop believing that commands are applied immediately (hopefully).
- Close #5913.
- Alternative to #5930.

## Solution

I added the clause “to perform impactful changes to the `World`” to the first line to subliminally help the reader accept the fact that some operations cannot be performed immediately without messing up everything.

Then I explicitely said that applying a command requires exclusive `World` access, and finally I proceeded to show when these commands are automatically applied.

I also added a brief paragraph about how commands can be applied manually, if they want.

---

### Further possibilities

If you agree, we can also change the text of the method documentation (in a separate PR) to stress about enqueueing an action instead of just performing it. For example, in `Commands::spawn`:

> Creates a new `Entity`

would be changed to something like:

> Issues a `Command` to spawn a new `Entity`

This may even have a greater effect, since when typing in an IDE, the docs of the method pop up and the programmer can read them on the fly.
This commit is contained in:
Federico Rinaldi 2022-09-12 01:06:09 +00:00
parent f83a9c23f2
commit fc07557913

View file

@ -45,9 +45,14 @@ pub trait Command: Send + Sync + 'static {
fn write(self, world: &mut World);
}
/// A queue of [commands](Command) that get executed at the end of the stage of the system that called them.
/// A [`Command`] queue to perform impactful changes to the [`World`].
///
/// Commands are executed one at a time in an exclusive fashion.
/// Since each command requires exclusive access to the `World`,
/// all queued commands are automatically applied in sequence
/// only after each system in a [stage] has completed.
///
/// The command queue of a system can also be manually applied
/// by calling [`System::apply_buffers`].
///
/// Each command can be used to modify the [`World`] in arbitrary ways:
/// * spawning or despawning entities
@ -88,6 +93,9 @@ pub trait Command: Send + Sync + 'static {
/// });
/// # }
/// ```
///
/// [stage]: crate::schedule::SystemStage
/// [`System::apply_buffers`]: crate::system::System::apply_buffers
pub struct Commands<'w, 's> {
queue: &'s mut CommandQueue,
entities: &'w Entities,