Add more comprehensive xmldoc for beatmap model classes

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
     {

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")]

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")]

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

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
     {

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
     {