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
{
- ///
- /// A Beatmap containing converted HitObjects.
- ///
public class Beatmap : IBeatmap
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
{
///
- /// 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.
///
+ ///
+ /// 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`.
+ ///
[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
{
+ ///
+ /// A realm model containing metadata for a beatmap.
+ ///
+ ///
+ /// This is currently stored against each beatmap difficulty, even when it is duplicated.
+ /// It is also provided via for convenience and historical purposes.
+ /// A future effort could see this converted to an 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 .
+ ///
[ExcludeFromDynamicCompile]
[Serializable]
[MapTo("BeatmapMetadata")]
diff --git a/osu.Game/Beatmaps/BeatmapSetInfo.cs b/osu.Game/Beatmaps/BeatmapSetInfo.cs
index b404f0b34d..d27d9d9192 100644
--- a/osu.Game/Beatmaps/BeatmapSetInfo.cs
+++ b/osu.Game/Beatmaps/BeatmapSetInfo.cs
@@ -14,6 +14,9 @@ using Realms;
namespace osu.Game.Beatmaps
{
+ ///
+ /// A realm model containing metadata for a beatmap set (containing multiple s).
+ ///
[ExcludeFromDynamicCompile]
[MapTo("BeatmapSet")]
public class BeatmapSetInfo : RealmObject, IHasGuidPrimaryKey, IHasRealmFiles, ISoftDelete, IEquatable, 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
{
+ ///
+ /// A materialised beatmap.
+ /// Generally this interface will be implemented alongside , which exposes the ruleset-typed hit objects.
+ ///
public interface IBeatmap
{
///
@@ -65,6 +69,9 @@ namespace osu.Game.Beatmaps
IBeatmap Clone();
}
+ ///
+ /// A materialised beatmap containing converted HitObjects.
+ ///
public interface IBeatmap : 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
{
///
- /// 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 .
+ /// - Access the storyboard via .
+ /// - Access a local skin via .
+ /// - Access the track via (and then for subsequent accesses).
+ /// - Create a playable via .
///
public interface IWorkingBeatmap
{