Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-26 06:30:19 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update API docs for Commands::get_or_spawn to inform the user about invalid returned values (#6117)

Browse source 
# Objective

As explained by #5960, `Commands::get_or_spawn` may return a dangling `EntityCommands` that references a non-existing entities. As explained in [this comment], it may be undesirable to make the method return an `Option`.

- Addresses #5960
- Alternative to #5961

## Solution

This PR adds a doc comment to the method to inform the user that the returned `EntityCommands` is not guaranteed to be valid. It also adds panic doc comments on appropriate `EntityCommands` methods.

[this comment]: https://github.com/bevyengine/bevy/pull/5961#issuecomment-1259870849
This commit is contained in:
Federico Rinaldi 2022-09-28 14:09:39 +00:00
parent 197392a2cd
commit aa32a77fdd
1 changed files with 15 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
crates/bevy_ecs/src/system/commands/mod.rs
View file

@ -168,6 +168,9 @@ impl<'w, 's> Commands<'w, 's> {
/// Pushes a [`Command`] to the queue for creating a new [`Entity`] if the given one does not exists,
/// and returns its corresponding [`EntityCommands`].
///
/// This method silently fails by returning `EntityCommands`
/// even if the given `Entity` cannot be spawned.
///
/// See [`World::get_or_spawn`] for more details.
///
/// # Note
@ -562,6 +565,10 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> {
/// Adds a [`Bundle`] of components to the entity.
///
/// # Panics
///
/// The command will panic when applied if the associated entity does not exist.
///
/// # Example
///
/// ```
@ -683,6 +690,10 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> {
///
/// See [`World::despawn`] for more details.
///
/// # Panics
///
/// The command will panic when applied if the associated entity does not exist.
///
/// # Example
///
/// ```
@ -707,6 +718,10 @@ impl<'w, 's, 'a> EntityCommands<'w, 's, 'a> {
}
/// Logs the components of the entity at the info level.
///
/// # Panics
///
/// The command will panic when applied if the associated entity does not exist.
pub fn log_components(&mut self) {
self.commands.add(LogComponents {
entity: self.entity,