From b72f06fef68a219b599671cefe3ce2e2b252d3e9 Mon Sep 17 00:00:00 2001
From: Dean Herbert <pe@ppy.sh>
Date: Sat, 22 Aug 2020 19:42:34 +0900
Subject: [PATCH] Centralise and clarify LoadTrack documentation

---
 osu.Game/Beatmaps/IWorkingBeatmap.cs | 10 +++++++++-
 osu.Game/Beatmaps/WorkingBeatmap.cs  |  4 ----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/osu.Game/Beatmaps/IWorkingBeatmap.cs b/osu.Game/Beatmaps/IWorkingBeatmap.cs
index 88d73fd7c4..bcd94d76fd 100644
--- a/osu.Game/Beatmaps/IWorkingBeatmap.cs
+++ b/osu.Game/Beatmaps/IWorkingBeatmap.cs
@@ -56,8 +56,16 @@ namespace osu.Game.Beatmaps
         IBeatmap GetPlayableBeatmap(RulesetInfo ruleset, IReadOnlyList<Mod> mods = null, TimeSpan? timeout = null);
 
         /// <summary>
-        /// Retrieves the <see cref="Track"/> which this <see cref="WorkingBeatmap"/> provides.
+        /// Load a new audio track instance for this beatmap. This should be called once before accessing <see cref="Track"/>.
+        /// The caller of this method is responsible for the lifetime of the track.
         /// </summary>
+        /// <remarks>
+        /// In a standard game context, the loading of the track is managed solely by MusicController, which will
+        /// automatically load the track of the current global IBindable WorkingBeatmap.
+        /// As such, this method should only be called in very special scenarios, such as external tests or apps which are
+        /// outside of the game context.
+        /// </remarks>
+        /// <returns>A fresh track instance, which will also be available via <see cref="Track"/>.</returns>
         Track LoadTrack();
     }
 }
diff --git a/osu.Game/Beatmaps/WorkingBeatmap.cs b/osu.Game/Beatmaps/WorkingBeatmap.cs
index 6a89739e6f..6a161e6e04 100644
--- a/osu.Game/Beatmaps/WorkingBeatmap.cs
+++ b/osu.Game/Beatmaps/WorkingBeatmap.cs
@@ -261,10 +261,6 @@ namespace osu.Game.Beatmaps
 
         private Track loadedTrack;
 
-        /// <summary>
-        /// Load a new audio track instance for this beatmap.
-        /// </summary>
-        /// <returns>A fresh track instance, which will also be available via <see cref="Track"/>.</returns>
         [NotNull]
         public Track LoadTrack() => loadedTrack = GetBeatmapTrack() ?? GetVirtualTrack(1000);