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

# 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

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