From 452d82f29239337af44a287e3b14d4e61730496f Mon Sep 17 00:00:00 2001
From: Dean Herbert <pe@ppy.sh>
Date: Thu, 28 Jul 2022 15:41:28 +0900
Subject: [PATCH 1/2] Add more comprehensive xmldoc for beatmap model classes

---
 osu.Game/Beatmaps/Beatmap.cs         |  3 ---
 osu.Game/Beatmaps/BeatmapInfo.cs     |  6 +++++-
 osu.Game/Beatmaps/BeatmapMetadata.cs | 11 +++++++++++
 osu.Game/Beatmaps/BeatmapSetInfo.cs  |  3 +++
 osu.Game/Beatmaps/IBeatmap.cs        |  7 +++++++
 osu.Game/Beatmaps/IWorkingBeatmap.cs |  7 ++++++-
 6 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/osu.Game/Beatmaps/Beatmap.cs b/osu.Game/Beatmaps/Beatmap.cs
index c499bccb68..2d02fb6200 100644
--- a/osu.Game/Beatmaps/Beatmap.cs
+++ b/osu.Game/Beatmaps/Beatmap.cs
@@ -14,9 +14,6 @@ using osu.Game.IO.Serialization.Converters;
 
 namespace osu.Game.Beatmaps
 {
-    /// <summary>
-    /// A Beatmap containing converted HitObjects.
-    /// </summary>
     public class Beatmap<T> : IBeatmap<T>
         where T : HitObject
     {
diff --git a/osu.Game/Beatmaps/BeatmapInfo.cs b/osu.Game/Beatmaps/BeatmapInfo.cs
index 66c1995c8b..f368f369ae 100644
--- a/osu.Game/Beatmaps/BeatmapInfo.cs
+++ b/osu.Game/Beatmaps/BeatmapInfo.cs
@@ -20,8 +20,12 @@ using Realms;
 namespace osu.Game.Beatmaps
 {
     /// <summary>
-    /// A single beatmap difficulty.
+    /// A realm model containing metadata for a single beatmap difficulty.
+    /// This should generally include anything which is required to be filtered on at song select, or anything pertaining to storage of beatmaps in the client.
     /// </summary>
+    /// <remarks>
+    /// There are some legacy fields in this model which are not persisted to realm. These are isolated in a code region within the class and should eventually be migrated to `Beatmap`.
+    /// </remarks>
     [ExcludeFromDynamicCompile]
     [Serializable]
     [MapTo("Beatmap")]
diff --git a/osu.Game/Beatmaps/BeatmapMetadata.cs b/osu.Game/Beatmaps/BeatmapMetadata.cs
index feb9d34f44..f645d914b1 100644
--- a/osu.Game/Beatmaps/BeatmapMetadata.cs
+++ b/osu.Game/Beatmaps/BeatmapMetadata.cs
@@ -12,6 +12,17 @@ using Realms;
 
 namespace osu.Game.Beatmaps
 {
+    /// <summary>
+    /// A realm model containing metadata for a beatmap.
+    /// </summary>
+    /// <remarks>
+    /// This is currently stored against each beatmap difficulty, even when it is duplicated.
+    /// It is also provided via <see cref="BeatmapSetInfo"/> for convenience and historical purposes.
+    /// A future effort could see this converted to an <see cref="EmbeddedObject"/> or potentially de-duped
+    /// and shared across multiple difficulties in the same set, if required.
+    ///
+    /// Note that difficulty name is not stored in this metadata but in <see cref="BeatmapInfo"/>.
+    /// </remarks>
     [ExcludeFromDynamicCompile]
     [Serializable]
     [MapTo("BeatmapMetadata")]
diff --git a/osu.Game/Beatmaps/BeatmapSetInfo.cs b/osu.Game/Beatmaps/BeatmapSetInfo.cs
index b404f0b34d..7f65d1291d 100644
--- a/osu.Game/Beatmaps/BeatmapSetInfo.cs
+++ b/osu.Game/Beatmaps/BeatmapSetInfo.cs
@@ -14,6 +14,9 @@ using Realms;
 
 namespace osu.Game.Beatmaps
 {
+    /// <summary>
+    /// A realm model containing metadata for a beatmap set (containing multiple <see cref="Beatmaps"/>).
+    /// </summary>
     [ExcludeFromDynamicCompile]
     [MapTo("BeatmapSet")]
     public class BeatmapSetInfo : RealmObject, IHasGuidPrimaryKey, IHasRealmFiles, ISoftDelete, IEquatable<BeatmapSetInfo>, IBeatmapSetInfo
diff --git a/osu.Game/Beatmaps/IBeatmap.cs b/osu.Game/Beatmaps/IBeatmap.cs
index 25b147c267..0e892b6581 100644
--- a/osu.Game/Beatmaps/IBeatmap.cs
+++ b/osu.Game/Beatmaps/IBeatmap.cs
@@ -11,6 +11,10 @@ using osu.Game.Rulesets.Scoring;
 
 namespace osu.Game.Beatmaps
 {
+    /// <summary>
+    /// A materialised beatmap.
+    /// Generally this interface will be implemented alongside <see cref="IBeatmap{T}"/>, which exposes the ruleset-typed hit objects.
+    /// </summary>
     public interface IBeatmap
     {
         /// <summary>
@@ -65,6 +69,9 @@ namespace osu.Game.Beatmaps
         IBeatmap Clone();
     }
 
+    /// <summary>
+    /// A materialised beatmap containing converted HitObjects.
+    /// </summary>
     public interface IBeatmap<out T> : IBeatmap
         where T : HitObject
     {
diff --git a/osu.Game/Beatmaps/IWorkingBeatmap.cs b/osu.Game/Beatmaps/IWorkingBeatmap.cs
index 2188bd6a2b..548341cc77 100644
--- a/osu.Game/Beatmaps/IWorkingBeatmap.cs
+++ b/osu.Game/Beatmaps/IWorkingBeatmap.cs
@@ -18,7 +18,12 @@ using osu.Game.Storyboards;
 namespace osu.Game.Beatmaps
 {
     /// <summary>
-    /// Provides access to the multiple resources offered by a beatmap model (textures, skins, playable beatmaps etc.)
+    /// A more expensive representation of a beatmap which allows access to various associated resources.
+    /// - Access textures and other resources via <see cref="GetStream"/>.
+    /// - Access the storyboard via <see cref="Storyboard"/>.
+    /// - Access a local skin via <see cref="Skin"/>.
+    /// - Access the track via <see cref="LoadTrack"/> (and then <see cref="Track"/> for subsequent accesses).
+    /// - Create a playable <see cref="Beatmap"/> via <see cref="GetPlayableBeatmap(osu.Game.Rulesets.IRulesetInfo,System.Collections.Generic.IReadOnlyList{osu.Game.Rulesets.Mods.Mod})"/>.
     /// </summary>
     public interface IWorkingBeatmap
     {

From c1aaf27c54bc2d996086c275c19556a7f163f9e5 Mon Sep 17 00:00:00 2001
From: Dan Balasescu <smoogipoo@smgi.me>
Date: Thu, 28 Jul 2022 16:02:19 +0900
Subject: [PATCH 2/2] Link to correct model in xmldoc

---
 osu.Game/Beatmaps/BeatmapSetInfo.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/osu.Game/Beatmaps/BeatmapSetInfo.cs b/osu.Game/Beatmaps/BeatmapSetInfo.cs
index 7f65d1291d..d27d9d9192 100644
--- a/osu.Game/Beatmaps/BeatmapSetInfo.cs
+++ b/osu.Game/Beatmaps/BeatmapSetInfo.cs
@@ -15,7 +15,7 @@ using Realms;
 namespace osu.Game.Beatmaps
 {
     /// <summary>
-    /// A realm model containing metadata for a beatmap set (containing multiple <see cref="Beatmaps"/>).
+    /// A realm model containing metadata for a beatmap set (containing multiple <see cref="BeatmapInfo"/>s).
     /// </summary>
     [ExcludeFromDynamicCompile]
     [MapTo("BeatmapSet")]