From 16a286dac364ec94e1f4d13a43b7683c09b641ef Mon Sep 17 00:00:00 2001
From: theotherphil <phil.j.ellison@gmail.com>
Date: Mon, 26 May 2025 21:27:20 +0100
Subject: [PATCH] Update .entry() docs to show both insert-then-modify and
 modify-or-insert examples (#19327)

# Objective

Fix https://github.com/bevyengine/bevy/issues/16379
---
 crates/bevy_ecs/src/system/commands/mod.rs | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs
index cbca7ec449..d6322eb733 100644
--- a/crates/bevy_ecs/src/system/commands/mod.rs
+++ b/crates/bevy_ecs/src/system/commands/mod.rs
@@ -1273,15 +1273,32 @@ impl<'a> EntityCommands<'a> {
     /// #[derive(Component)]
     /// struct Level(u32);
     ///
+    ///
+    /// #[derive(Component, Default)]
+    /// struct Mana {
+    ///     max: u32,
+    ///     current: u32,
+    /// }
+    ///
     /// fn level_up_system(mut commands: Commands, player: Res<PlayerEntity>) {
+    ///     // If a component already exists then modify it, otherwise insert a default value
     ///     commands
     ///         .entity(player.entity)
     ///         .entry::<Level>()
-    ///         // Modify the component if it exists.
     ///         .and_modify(|mut lvl| lvl.0 += 1)
-    ///         // Otherwise, insert a default value.
     ///         .or_insert(Level(0));
+    ///
+    ///     // Add a default value if none exists, and then modify the existing or new value
+    ///     commands
+    ///         .entity(player.entity)
+    ///         .entry::<Mana>()
+    ///         .or_default()
+    ///         .and_modify(|mut mana| {
+    ///             mana.max += 10;
+    ///             mana.current = mana.max;
+    ///     });
     /// }
+    ///
     /// # bevy_ecs::system::assert_is_system(level_up_system);
     /// ```
     pub fn entry<T: Component>(&mut self) -> EntityEntryCommands<T> {