Mention Mut in QueryData docs, clarify behaviour of Mut vs &mut in Mut docs (#19254)

# Objective

- Fix #13843
- Clarify the difference between Mut and &mut when accessing query data

## Solution

- Mention `Mut` in `QueryData` docs as an example of a type that
implements this trait
- Give example of `iter_mut` vs `iter` access to `Mut` and `& mut`
parameters

## Testing

-

Author: theotherphil

crates/bevy_ecs/src/change_detection.rs

@@ -898,63 +898,39 @@ impl_debug!(Ref<'w, T>,);
 
 /// Unique mutable borrow of an entity's component or of a resource.
 ///
-/// This can be used in queries to opt into change detection on both their mutable and immutable forms, as opposed to
-/// `&mut T`, which only provides access to change detection while in its mutable form:
+/// This can be used in queries to access change detection from immutable query methods, as opposed
+/// to `&mut T` which only provides access to change detection from mutable query methods.
 ///
 /// ```rust
 /// # use bevy_ecs::prelude::*;
 /// # use bevy_ecs::query::QueryData;
 /// #
-/// #[derive(Component, Clone)]
+/// #[derive(Component, Clone, Debug)]
 /// struct Name(String);
 ///
-/// #[derive(Component, Clone, Copy)]
+/// #[derive(Component, Clone, Copy, Debug)]
 /// struct Health(f32);
 ///
-/// #[derive(Component, Clone, Copy)]
-/// struct Position {
-///     x: f32,
-///     y: f32,
-/// };
-///
-/// #[derive(Component, Clone, Copy)]
-/// struct Player {
-///     id: usize,
-/// };
-///
-/// #[derive(QueryData)]
-/// #[query_data(mutable)]
-/// struct PlayerQuery {
-///     id: &'static Player,
-///
-///     // Reacting to `PlayerName` changes is expensive, so we need to enable change detection when reading it.
-///     name: Mut<'static, Name>,
-///
-///     health: &'static mut Health,
-///     position: &'static mut Position,
-/// }
-///
-/// fn update_player_avatars(players_query: Query<PlayerQuery>) {
-///     // The item returned by the iterator is of type `PlayerQueryReadOnlyItem`.
-///     for player in players_query.iter() {
-///         if player.name.is_changed() {
-///             // Update the player's name. This clones a String, and so is more expensive.
-///             update_player_name(player.id, player.name.clone());
-///         }
-///
-///         // Update the health bar.
-///         update_player_health(player.id, *player.health);
+/// fn my_system(mut query: Query<(Mut<Name>, &mut Health)>) {
+///     // Mutable access provides change detection information for both parameters:
+///     // - `name` has type `Mut<Name>`
+///     // - `health` has type `Mut<Health>`
+///     for (name, health) in query.iter_mut() {
+///         println!("Name: {:?} (last changed {:?})", name, name.last_changed());
+///         println!("Health: {:?} (last changed: {:?})", health, health.last_changed());
+/// #        println!("{}{}", name.0, health.0); // Silence dead_code warning
+///     }
 ///
-///         // Update the player's position.
-///         update_player_position(player.id, *player.position);
+///     // Immutable access only provides change detection for `Name`:
+///     // - `name` has type `Ref<Name>`
+///     // - `health` has type `&Health`
+///     for (name, health) in query.iter() {
+///         println!("Name: {:?} (last changed {:?})", name, name.last_changed());
+///         println!("Health: {:?}", health);
 ///     }
 /// }
 ///
-/// # bevy_ecs::system::assert_is_system(update_player_avatars);
-///
-/// # fn update_player_name(player: &Player, new_name: Name) {}
-/// # fn update_player_health(player: &Player, new_health: Health) {}
-/// # fn update_player_position(player: &Player, new_position: Position) {}
+/// # bevy_ecs::system::assert_is_system(my_system);
 /// ```
 pub struct Mut<'w, T: ?Sized> {
     pub(crate) value: &'w mut T,

crates/bevy_ecs/src/query/fetch.rs

@@ -47,6 +47,8 @@ use variadics_please::all_tuples;
 /// - **[`Ref`].**
 ///   Similar to change detection filters but it is used as a query fetch parameter.
 ///   It exposes methods to check for changes to the wrapped component.
+/// - **[`Mut`].**
+///   Mutable component access, with change detection data.
 /// - **[`Has`].**
 ///   Returns a bool indicating whether the entity has the specified component.
 ///