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:
parent
f83a9c23f2
commit
fc07557913
@ -45,9 +45,14 @@ pub trait Command: Send + Sync + 'static {
|
|||||||
fn write(self, world: &mut World);
|
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:
|
/// Each command can be used to modify the [`World`] in arbitrary ways:
|
||||||
/// * spawning or despawning entities
|
/// * 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> {
|
pub struct Commands<'w, 's> {
|
||||||
queue: &'s mut CommandQueue,
|
queue: &'s mut CommandQueue,
|
||||||
entities: &'w Entities,
|
entities: &'w Entities,
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user