State that QueryCombinationIter implements Iterator only when it …

…iterates over read-only query items

crates/bevy_ecs/src/query/iter.rs

@@ -195,26 +195,43 @@ where
 ///
 /// # Usage
 ///
-/// This type is returned by calling [`Query::iter_combinations`] and related methods.
+/// This type is returned by calling [`Query::iter_combinations`] or [`Query::iter_combinations_mut`].
 ///
-/// It can be iterated by calling [`fetch_next`](Self::fetch_next) in a `while let` loop.
+/// It implements [`Iterator`] only if it iterates over read-only query items ([learn more]).
+///
+/// In the case of mutable query items, it can be iterated by calling [`fetch_next`](Self::fetch_next) in a `while let` loop.
 ///
-/// [compiler bug]: https://github.com/rust-lang/rust/issues/62529
 /// [`Query`]: crate::system::Query
 /// [performance section]: crate::system::Query#performance
 /// [`Query::iter_combinations`]: crate::system::Query::iter_combinations
+/// [`Query::iter_combinations_mut`]: crate::system::Query::iter_combinations_mut
+/// [learn more]: Self#impl-Iterator
+///
+/// # Examples
+///
+/// The following example shows how to traverse the iterator when the query items are read-only.
 ///
-/// # Example
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # #[derive(Component)]
+/// # struct ComponentA;
+/// #
+/// fn some_system(query: Query<&ComponentA>) {
+///     for [a1, a2] in query.iter_combinations() {
+///         // ...
+///     }
+/// }
+/// ```
 ///
-/// This example shows how `fetch_next` should be called with a `while let` loop to traverse the iterator.
+/// The following example shows how `fetch_next` should be called with a `while let` loop to traverse the iterator when the query items are mutable.
 ///
 /// ```
 /// # use bevy_ecs::prelude::*;
 /// # #[derive(Component)]
 /// # struct ComponentA;
 /// #
 /// fn some_system(mut query: Query<&mut ComponentA>) {
-///     let mut combinations = query.iter_combinations();
+///     let mut combinations = query.iter_combinations_mut();
 ///     while let Some([a1, a2]) = combinations.fetch_next() {
 ///         // ...
 ///     }
@@ -334,9 +351,8 @@ impl<'w, 's, Q: WorldQuery, F: WorldQuery, const K: usize> QueryCombinationIter<
     }
 }
 
-// Iterator type is intentionally implemented only for read-only access.
-// Doing so for mutable references would be unsound, because  calling `next`
-// multiple times would allow multiple owned references to the same data to exist.
+/// Iterator type is intentionally implemented only for read-only access.
+/// Doing so for mutable references would be unsound, because  calling `next` multiple times would allow multiple owned references to the same data to exist.
 impl<'w, 's, Q: WorldQuery, F: WorldQuery, const K: usize> Iterator
     for QueryCombinationIter<'w, 's, Q, F, K>
 where

crates/bevy_ecs/src/system/query.rs

@@ -374,9 +374,8 @@ impl<'w, 's, Q: WorldQuery, F: WorldQuery> Query<'w, 's, Q, F> {
     /// # #[derive(Component)]
     /// # struct ComponentA;
     /// #
-    /// fn some_system(mut query: Query<&mut ComponentA>) {
-    ///     let mut combinations = query.iter_combinations();
-    ///     while let Some([a1, a2]) = combinations.fetch_next() {
+    /// fn some_system(query: Query<&ComponentA>) {
+    ///     for [a1, a2] in query.iter_combinations() {
     ///         // ...
     ///     }
     /// }