Clarify behaviour of Timer::finished() for repeating timers (bevyen…

…gine#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

@@ -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 {