From bcc153f7387c0eb8273990397d6e9bb113f698b0 Mon Sep 17 00:00:00 2001
From: Dean Herbert <pe@ppy.sh>
Date: Thu, 18 Aug 2022 15:01:47 +0900
Subject: [PATCH] Add xmldoc and reorganise `FramedBeatmapClock`

---
 osu.Game/Beatmaps/FramedBeatmapClock.cs | 45 +++++++++++++++----------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/osu.Game/Beatmaps/FramedBeatmapClock.cs b/osu.Game/Beatmaps/FramedBeatmapClock.cs
index f3219b972e..90ff0588a6 100644
--- a/osu.Game/Beatmaps/FramedBeatmapClock.cs
+++ b/osu.Game/Beatmaps/FramedBeatmapClock.cs
@@ -15,6 +15,15 @@ using osu.Game.Screens.Play;
 
 namespace osu.Game.Beatmaps
 {
+    /// <summary>
+    /// A clock intended to be the single source-of-truth for beatmap timing.
+    ///
+    /// It provides some functionality:
+    ///  - Applies (and tracks changes of) beatmap, user, and platform offsets.
+    ///  - Adjusts <see cref="Seek"/> operations to account for said offsets, seeking in raw time values.
+    ///  - Exposes track length.
+    ///  - Allows changing the source to a new track (for cases like editor track updating).
+    /// </summary>
     public class FramedBeatmapClock : Component, IFrameBasedClock, IAdjustableClock, ISourceChangeableClock
     {
         private readonly bool applyOffsets;
@@ -46,21 +55,6 @@ namespace osu.Game.Beatmaps
 
         private readonly DecoupleableInterpolatingFramedClock decoupledClock;
 
-        private double totalAppliedOffset
-        {
-            get
-            {
-                if (!applyOffsets)
-                    return 0;
-
-                Debug.Assert(userGlobalOffsetClock != null);
-                Debug.Assert(userBeatmapOffsetClock != null);
-                Debug.Assert(platformOffsetClock != null);
-
-                return userGlobalOffsetClock.RateAdjustedOffset + userBeatmapOffsetClock.RateAdjustedOffset + platformOffsetClock.RateAdjustedOffset;
-            }
-        }
-
         [Resolved]
         private OsuConfigManager config { get; set; } = null!;
 
@@ -131,10 +125,19 @@ namespace osu.Game.Beatmaps
             finalClockSource.ProcessFrame();
         }
 
-        protected override void Dispose(bool isDisposing)
+        private double totalAppliedOffset
         {
-            base.Dispose(isDisposing);
-            beatmapOffsetSubscription?.Dispose();
+            get
+            {
+                if (!applyOffsets)
+                    return 0;
+
+                Debug.Assert(userGlobalOffsetClock != null);
+                Debug.Assert(userBeatmapOffsetClock != null);
+                Debug.Assert(platformOffsetClock != null);
+
+                return userGlobalOffsetClock.RateAdjustedOffset + userBeatmapOffsetClock.RateAdjustedOffset + platformOffsetClock.RateAdjustedOffset;
+            }
         }
 
         #region Delegation of IAdjustableClock / ISourceChangeableClock to decoupled clock.
@@ -201,5 +204,11 @@ namespace osu.Game.Beatmaps
         public FrameTimeInfo TimeInfo => finalClockSource.TimeInfo;
 
         #endregion
+
+        protected override void Dispose(bool isDisposing)
+        {
+            base.Dispose(isDisposing);
+            beatmapOffsetSubscription?.Dispose();
+        }
     }
 }