From b4e7f0899a9841e0b8972ed528d0dddb19c9c2aa Mon Sep 17 00:00:00 2001
From: JoJoJet <21144246+JoJoJet@users.noreply.github.com>
Date: Fri, 19 May 2023 14:24:11 -0400
Subject: [PATCH] Add documentation to `last_change_tick` (#8598)

# Objective

This method has no documentation and it's extremely unclear what it
does, or what the returned tick represents.

## Solution

Write documentation.
---
 crates/bevy_ecs/src/world/mod.rs               |  6 ++++++
 crates/bevy_ecs/src/world/unsafe_world_cell.rs | 11 ++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs
index f270e85105..168c550ed2 100644
--- a/crates/bevy_ecs/src/world/mod.rs
+++ b/crates/bevy_ecs/src/world/mod.rs
@@ -1499,6 +1499,12 @@ impl World {
         Tick::new(tick)
     }
 
+    /// When called from within an exclusive system (a [`System`] that takes `&mut World` as its first
+    /// parameter), this method returns the [`Tick`] indicating the last time the exclusive system was run.
+    ///
+    /// Otherwise, this returns the `Tick` indicating the last time that [`World::clear_trackers`] was called.
+    ///
+    /// [`System`]: crate::system::System
     #[inline]
     pub fn last_change_tick(&self) -> Tick {
         self.last_change_tick
diff --git a/crates/bevy_ecs/src/world/unsafe_world_cell.rs b/crates/bevy_ecs/src/world/unsafe_world_cell.rs
index f6849b92c8..85a086e745 100644
--- a/crates/bevy_ecs/src/world/unsafe_world_cell.rs
+++ b/crates/bevy_ecs/src/world/unsafe_world_cell.rs
@@ -237,11 +237,20 @@ impl<'w> UnsafeWorldCell<'w> {
         unsafe { self.world_metadata() }.read_change_tick()
     }
 
+    /// Returns the [`Tick`] indicating the last time that [`World::clear_trackers`] was called.
+    ///
+    /// If this `UnsafeWorldCell` was created from inside of an exclusive system (a [`System`] that
+    /// takes `&mut World` as its first parameter), this will instead return the `Tick` indicating
+    /// the last time the system was run.
+    ///
+    /// See [`World::last_change_tick()`].
+    ///
+    /// [`System`]: crate::system::System
     #[inline]
     pub fn last_change_tick(self) -> Tick {
         // SAFETY:
         // - we only access world metadata
-        unsafe { self.world_metadata() }.last_change_tick
+        unsafe { self.world_metadata() }.last_change_tick()
     }
 
     #[inline]