Basic doc tests

crates/bevy_ecs/src/query/state.rs

@@ -159,6 +159,32 @@ where
     /// returned instead.
     ///
     /// Note that the unlike [`QueryState::get_multiple_mut`], the entities passed in do not need to be unique.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component, PartialEq, Debug)]
+    /// struct A(usize);
+    ///
+    /// let mut world = World::new();
+    /// let mut entities: [Entity; 3] = [Entity::from_raw(0); 3];
+    ///
+    /// world.spawn().insert(A(42));
+    ///
+    /// for i in 0..3 {
+    ///     entities[i] = world.spawn().insert(A(i)).id();
+    /// }
+    ///
+    /// world.spawn().insert(A(73));
+    ///
+    /// let mut query_state = world.query::<&A>();
+    ///
+    /// let component_values = query_state.get_multiple(&world, entities).unwrap();
+    ///
+    /// assert_eq!(component_values, [&A(0), &A(1), &A(2)])
+    /// ```
     #[inline]
     pub fn get_multiple<'w, 's, const N: usize>(
         &'s mut self,
@@ -213,6 +239,36 @@ where
     ///
     /// In case of a nonexisting entity or mismatched component, a [`QueryEntityError`] is
     /// returned instead.
+    ///
+    /// ```rust
+    /// use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component, PartialEq, Debug)]
+    /// struct A(usize);
+    ///
+    /// let mut world = World::new();
+    /// let mut entities: [Entity; 3] = [Entity::from_raw(0); 3];
+    ///
+    /// world.spawn().insert(A(42));
+    ///
+    /// for i in 0..3 {
+    ///     entities[i] = world.spawn().insert(A(i)).id();
+    /// }
+    ///
+    /// world.spawn().insert(A(73));
+    ///
+    /// let mut query_state = world.query::<&mut A>();
+    ///
+    /// let mut mutable_component_values = query_state.get_multiple_mut(&mut world, entities).unwrap();
+    ///
+    /// for mut a in mutable_component_values.iter_mut(){
+    ///     a.0 += 5;
+    /// }
+    ///
+    /// let component_values = query_state.get_multiple(&world, entities).unwrap();
+    ///
+    /// assert_eq!(component_values, [&A(5), &A(6), &A(7)])
+    /// ```
     #[inline]
     pub fn get_multiple_mut<'w, 's, const N: usize>(
         &'s mut self,

crates/bevy_ecs/src/system/query.rs

@@ -624,6 +624,8 @@ where
     /// returned instead.
     ///
     /// Note that the unlike [`Query::get_multiple_mut`], the entities passed in do not need to be unique.
+    ///
+    /// See [`Query::multiple`] for the infallible equivalent.
     #[inline]
     pub fn get_multiple<const N: usize>(
         &'s self,
@@ -653,6 +655,40 @@ where
     }
 
     /// Returns the read-only query items for the provided array of [`Entity`]
+    ///
+    /// See [`Query::get_multiple`] for the [`Result`]-returning equivalent.
+    ///
+    /// # Examples
+    /// ```rust, no_run
+    /// use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component)]
+    /// struct Targets([Entity; 3]);
+    ///
+    /// #[derive(Component)]
+    /// struct Position{
+    ///     x: i8,
+    ///     y: i8
+    /// };
+    ///
+    /// impl Position {
+    ///     fn distance(&self, other: &Position) -> i8 {
+    ///         // Manhattan distance is way easier to compute!
+    ///         (self.x - other.x).abs() + (self.y - other.y).abs()
+    ///     }
+    /// }
+    ///
+    /// fn check_all_targets_in_range(targeting_query: Query<(Entity, &Targets, &Position)>, targets_query: Query<&Position>){
+    ///     for (targeting_entity, targets, origin) in targeting_query.iter(){
+    ///         // We can use "destructuring" to unpack the results nicely
+    ///         let [target_1, target_2, target_3] = targets_query.multiple(targets.0);
+    ///         
+    ///         assert!(target_1.distance(origin) <= 5);
+    ///         assert!(target_2.distance(origin) <= 5);
+    ///         assert!(target_3.distance(origin) <= 5);
+    ///     }
+    /// }
+    /// ```
     #[inline]
     pub fn multiple<const N: usize>(
         &'s self,
@@ -706,6 +742,8 @@ where
     ///
     /// In case of a nonexisting entity, duplicate entities or mismatched component, a [`QueryEntityError`] is
     /// returned instead.
+    ///
+    /// See [`Query::multiple_mut`] for the infallible equivalent.
     #[inline]
     pub fn get_multiple_mut<const N: usize>(
         &'s mut self,
@@ -745,6 +783,46 @@ where
     }
 
     /// Returns the query items for the provided array of [`Entity`]
+    ///
+    /// See [`Query::get_multiple_mut`] for the [`Result`]-returning equivalent.
+    ///
+    /// # Examples
+    ///
+    /// ```rust, no_run
+    /// use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(Component)]
+    /// struct Spring{
+    ///     connected_entities: [Entity; 2],
+    ///     strength: f32,
+    /// }
+    ///
+    /// #[derive(Component)]
+    /// struct Position {
+    ///     x: f32,
+    ///     y: f32,
+    /// }
+    ///
+    /// #[derive(Component)]
+    /// struct Force {
+    ///     x: f32,
+    ///     y: f32,
+    /// }
+    ///
+    /// fn spring_forces(spring_query: Query<&Spring>, mut mass_query: Query<(&Position, &mut Force)>){
+    ///     for spring in spring_query.iter(){
+    ///          // We can use "destructuring" to unpack our query items nicely
+    ///          let [(position_1, mut force_1), (position_2, mut force_2)] = mass_query.multiple_mut(spring.connected_entities);
+    ///             
+    ///          force_1.x += spring.strength * (position_1.x - position_2.x);
+    ///          force_1.y += spring.strength * (position_1.y - position_2.y);
+    ///          
+    ///          // Silence borrow-checker: I have split your mutable borrow!
+    ///          force_2.x += spring.strength * (position_2.x - position_1.x);
+    ///          force_2.y += spring.strength * (position_2.y - position_1.y);
+    ///     }
+    /// }
+    /// ```
     #[inline]
     pub fn multiple_mut<const N: usize>(
         &'s mut self,