forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix API docs for Commands methods (#5955)

Browse Source 
# Objective

The doc comments for `Command` methods are a bit inconsistent on the format, they sometimes go out of scope, and most importantly they are wrong, in the sense that they claim to perform the action described by the command, while in reality, they just push a command to perform the action.

- Follow-up of #5938.
- Related to #5913.

## Solution

- Where applicable, only stated that a `Command` is pushed.
- Added a “See also” section for similar methods.
- Added a missing “Panics” section for `Commands::entity`.
- Removed a wrong comment about `Commands::get_or_spawn` returning `None` (It does not return an option).
- Removed polluting descriptions of other items.
- Misc formatting changes.

## Future possibilities

Since the `Command` implementors (`Spawn`, `InsertBundle`, `InitResource`, ...) are public, I thought that it might be appropriate to describe the action of the command there instead of the method, and to add a `method → command struct` link to fill the gap.

If that seems too far-fetched, we may opt to make them private, if possible, or `#[doc(hidden)]`.
This commit is contained in:
Federico Rinaldi 2022-09-21 17:37:57 +00:00
parent 2eb9dd9dd9
commit d9e99cd80c
1 changed files with 84 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
crates/bevy_ecs/src/system/commands/mod.rs
View File

@ -102,7 +102,11 @@ pub struct Commands<'w, 's> {
}
impl<'w, 's> Commands<'w, 's> {
/// Create a new `Commands` from a queue and a world.
/// Returns a new `Commands` instance from a [`CommandQueue`] and a [`World`].
///
/// It is not required to call this constructor when using `Commands` as a [system parameter].
///
/// [system parameter]: crate::system::SystemParam
pub fn new(queue: &'s mut CommandQueue, world: &'w World) -> Self {
Self {
queue,
@ -110,15 +114,17 @@ impl<'w, 's> Commands<'w, 's> {
}
}
/// Create a new `Commands` from a queue and an [`Entities`] reference.
/// Returns a new `Commands` instance from a [`CommandQueue`] and an [`Entities`] reference.
///
/// It is not required to call this constructor when using `Commands` as a [system parameter].
///
/// [system parameter]: crate::system::SystemParam
pub fn new_from_entities(queue: &'s mut CommandQueue, entities: &'w Entities) -> Self {
Self { queue, entities }
}
/// Creates a new empty [`Entity`] and returns an [`EntityCommands`] builder for it.
///
/// To directly spawn an entity with a [`Bundle`] included, you can use
/// [`spawn_bundle`](Self::spawn_bundle) instead of `.spawn().insert_bundle()`.
/// Pushes a [`Command`] to the queue for creating a new empty [`Entity`],
/// and returns its corresponding [`EntityCommands`].
///
/// See [`World::spawn`] for more details.
///
@ -147,6 +153,11 @@ impl<'w, 's> Commands<'w, 's> {
/// }
/// # bevy_ecs::system::assert_is_system(example_system);
/// ```
///
/// # See also
///
/// - [`spawn_bundle`](Self::spawn_bundle) to spawn an entity with a bundle.
/// - [`spawn_batch`](Self::spawn_batch) to spawn entities with a bundle each.
pub fn spawn<'a>(&'a mut self) -> EntityCommands<'w, 's, 'a> {
let entity = self.entities.reserve_entity();
EntityCommands {
@ -155,10 +166,13 @@ impl<'w, 's> Commands<'w, 's> {
}
}
/// Returns an [`EntityCommands`] for the given `entity` (if it exists) or spawns one if it
/// doesn't exist. This will return [`None`] if the `entity` exists with a different generation.
/// Pushes a [`Command`] to the queue for creating a new [`Entity`] if the given one does not exists,
/// and returns its corresponding [`EntityCommands`].
///
/// See [`World::get_or_spawn`] for more details.
///
/// # Note
///
/// Spawning a specific `entity` value is rarely the right choice. Most apps should favor
/// [`Commands::spawn`]. This method should generally only be used for sharing entities across
/// apps, and only when they have a scheme worked out to share an ID space (which doesn't happen
@ -171,14 +185,8 @@ impl<'w, 's> Commands<'w, 's> {
}
}
/// Creates a new entity with the components contained in `bundle`.
///
/// This returns an [`EntityCommands`] builder, which enables inserting more components and
/// bundles using a "builder pattern".
///
/// Note that `bundle` is a [`Bundle`], which is a collection of components. [`Bundle`] is
/// automatically implemented for tuples of components. You can also create your own bundle
/// types by deriving [`derive@Bundle`].
/// Pushes a [`Command`] to the queue for creating a new entity with the given [`Bundle`]'s components,
/// and returns its corresponding [`EntityCommands`].
///
/// # Example
///
@ -219,13 +227,22 @@ impl<'w, 's> Commands<'w, 's> {
/// }
/// # bevy_ecs::system::assert_is_system(example_system);
/// ```
///
/// # See also
///
/// - [`spawn`](Self::spawn) to just spawn an entity without any component.
/// - [`spawn_batch`](Self::spawn_batch) to spawn entities with a bundle each.
pub fn spawn_bundle<'a, T: Bundle>(&'a mut self, bundle: T) -> EntityCommands<'w, 's, 'a> {
let mut e = self.spawn();
e.insert_bundle(bundle);
e
}
/// Returns an [`EntityCommands`] builder for the requested [`Entity`].
/// Returns the [`EntityCommands`] for the requested [`Entity`].
///
/// # Panics
///
/// This method panics if the requested entity does not exist.
///
/// # Example
///
@ -238,7 +255,7 @@ impl<'w, 's> Commands<'w, 's> {
/// struct Strength(u32);
/// #[derive(Component)]
/// struct Agility(u32);
///
/// fn example_system(mut commands: Commands) {
/// // Create a new, empty entity
/// let entity = commands.spawn().id();
@ -251,6 +268,10 @@ impl<'w, 's> Commands<'w, 's> {
/// }
/// # bevy_ecs::system::assert_is_system(example_system);
/// ```
///
/// # See also
///
/// - [`get_entity`](Self::get_entity) for the fallible version.
#[inline]
#[track_caller]
pub fn entity<'a>(&'a mut self, entity: Entity) -> EntityCommands<'w, 's, 'a> {
@ -262,8 +283,12 @@ impl<'w, 's> Commands<'w, 's> {
})
}
/// Returns an option containing an [`EntityCommands`] builder for the requested [`Entity`] if it exists, otherwise `None`.
/// This does not ensure that the commands will succeed as the entity may no longer exist by the time the associated commands are executed.
/// Returns the [`EntityCommands`] for the requested [`Entity`], if it exists.
///
/// Returns `None` if the entity does not exist.
///
/// This method does not guarantee that `EntityCommands` will be successfully applied,
/// since another command in the queue may delete the entity before them.
///
/// # Example
///
@ -285,6 +310,10 @@ impl<'w, 's> Commands<'w, 's> {
/// }
/// # bevy_ecs::system::assert_is_system(example_system);
/// ```
///
/// # See also
///
/// - [`entity`](Self::entity) for the panicking version.
#[inline]
#[track_caller]
pub fn get_entity<'a>(&'a mut self, entity: Entity) -> Option<EntityCommands<'w, 's, 'a>> {
@ -294,12 +323,14 @@ impl<'w, 's> Commands<'w, 's> {
})
}
/// Spawns entities to the [`World`] according to the given iterator (or a type that can
/// be converted to it).
/// Pushes a [`Command`] to the queue for creating entities with a particular [`Bundle`] type.
///
/// The end result of this command is equivalent to iterating `bundles_iter` and calling
/// [`spawn`](Self::spawn) on each bundle, but it is more performant due to memory
/// pre-allocation.
/// `bundles_iter` is a type that can be converted into a `Bundle` iterator
/// (it can also be a collection).
///
/// This method is equivalent to iterating `bundles_iter`
/// and calling [`spawn`](Self::spawn) on each bundle,
/// but it is faster due to memory pre-allocation.
///
/// # Example
///
@ -325,6 +356,11 @@ impl<'w, 's> Commands<'w, 's> {
/// # }
/// # bevy_ecs::system::assert_is_system(system);
/// ```
///
/// # See also
///
/// - [`spawn`](Self::spawn) to just spawn an entity without any component.
/// - [`spawn_bundle`](Self::spawn_bundle) to spawn an entity with a bundle.
pub fn spawn_batch<I>(&mut self, bundles_iter: I)
where
I: IntoIterator + Send + Sync + 'static,
@ -333,10 +369,21 @@ impl<'w, 's> Commands<'w, 's> {
self.queue.push(SpawnBatch { bundles_iter });
}
/// For a given batch of ([Entity], [Bundle]) pairs, either spawns each [Entity] with the given
/// bundle (if the entity does not exist), or inserts the [Bundle] (if the entity already exists).
/// Pushes a [`Command`] to the queue for creating entities, if needed,
/// and for adding a bundle to each entity.
///
/// This is faster than doing equivalent operations one-by-one.
/// `bundles_iter` is a type that can be converted into an ([`Entity`], [`Bundle`]) iterator
/// (it can also be a collection).
///
/// When the command is applied,
/// for each (`Entity`, `Bundle`) pair in the given `bundles_iter`,
/// the `Entity` is spawned, if it does not exist already.
/// Then, the `Bundle` is added to the entity.
///
/// This method is equivalent to iterating `bundles_iter`,
/// calling [`get_or_spawn`](Self::get_or_spawn) for each bundle,
/// and passing it to [`insert_bundle`](EntityCommands::insert_bundle),
/// but it is faster due to memory pre-allocation.
///
/// # Note
///
@ -352,17 +399,13 @@ impl<'w, 's> Commands<'w, 's> {
self.queue.push(InsertOrSpawnBatch { bundles_iter });
}
/// Inserts a resource with standard starting values to the [`World`].
/// Pushes a [`Command`] to the queue for inserting a [`Resource`] in the [`World`] with an inferred value.
///
/// If the resource already exists, nothing happens.
///
/// The value given by the [`FromWorld::from_world`] method will be used.
/// Note that any resource with the `Default` trait automatically implements `FromWorld`,
/// and those default values will be here instead.
/// The inferred value is determined by the [`FromWorld`] trait of the resource.
/// When the command is applied,
/// if the resource already exists, nothing happens.
///
/// See [`World::init_resource`] for more details.
/// Note that commands do not take effect immediately.
/// When possible, prefer the equivalent methods on `App` or `World`.
///
/// # Example
///
@ -386,11 +429,11 @@ impl<'w, 's> Commands<'w, 's> {
});
}
/// Inserts a resource to the [`World`], overwriting any previous value of the same type.
/// Pushes a [`Command`] to the queue for inserting a [`Resource`] in the [`World`] with a specific value.
///
/// This will overwrite any previous value of the same resource type.
///
/// See [`World::insert_resource`] for more details.
/// Note that commands do not take effect immediately.
/// When possible, prefer the equivalent methods on `App` or `World`.
///
/// # Example
///
@ -415,7 +458,7 @@ impl<'w, 's> Commands<'w, 's> {
self.queue.push(InsertResource { resource });
}
/// Removes a resource from the [`World`].
/// Pushes a [`Command`] to the queue for removing a [`Resource`] from the [`World`].
///
/// See [`World::remove_resource`] for more details.
///
@ -441,7 +484,7 @@ impl<'w, 's> Commands<'w, 's> {
});
}
/// Adds a command directly to the command queue.
/// Pushes a generic [`Command`] to the command queue.
///
/// `command` can be a built-in command, custom struct that implements [`Command`] or a closure
/// that takes [`&mut World`](World) as an argument.