From 14db5b38dcb183d78613385bac4cfb268ed16888 Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Sat, 30 Sep 2023 05:57:01 +0800
Subject: [PATCH] Clarify behaviour of `Timer::finished()` for repeating timers
 (#9939)

# Objective

I was wondering whether to use `Timer::finished` or
`Timer::just_finished` for my repeating timer. This PR clarifies their
difference (or rather, lack thereof).

## Solution

More docs & examples.
---
 crates/bevy_time/src/timer.rs | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/crates/bevy_time/src/timer.rs b/crates/bevy_time/src/timer.rs
index 3f0503e9fd847..e7152978ee561 100644
--- a/crates/bevy_time/src/timer.rs
+++ b/crates/bevy_time/src/timer.rs
@@ -47,18 +47,28 @@ impl Timer {
         }
     }
 
-    /// Returns `true` if the timer has reached its duration at least once.
-    /// See also [`Timer::just_finished`](Timer::just_finished).
+    /// Returns `true` if the timer has reached its duration.
+    ///
+    /// For repeating timers, this method behaves identically to [`Timer::just_finished`].
     ///
     /// # Examples
     /// ```
     /// # use bevy_time::*;
     /// use std::time::Duration;
-    /// let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
-    /// timer.tick(Duration::from_secs_f32(1.5));
-    /// assert!(timer.finished());
-    /// timer.tick(Duration::from_secs_f32(0.5));
-    /// assert!(timer.finished());
+    ///
+    /// let mut timer_once = Timer::from_seconds(1.0, TimerMode::Once);
+    /// timer_once.tick(Duration::from_secs_f32(1.5));
+    /// assert!(timer_once.finished());
+    /// timer_once.tick(Duration::from_secs_f32(0.5));
+    /// assert!(timer_once.finished());
+    ///
+    /// let mut timer_repeating = Timer::from_seconds(1.0, TimerMode::Repeating);
+    /// timer_repeating.tick(Duration::from_secs_f32(1.1));
+    /// assert!(timer_repeating.finished());
+    /// timer_repeating.tick(Duration::from_secs_f32(0.8));
+    /// assert!(!timer_repeating.finished());
+    /// timer_repeating.tick(Duration::from_secs_f32(0.6));
+    /// assert!(timer_repeating.finished());
     /// ```
     #[inline]
     pub fn finished(&self) -> bool {