From 04640b6fb0129aa880281d1883bf0b318a128fe0 Mon Sep 17 00:00:00 2001
From: Dean Herbert <pe@ppy.sh>
Date: Wed, 22 Nov 2023 10:44:29 +0900
Subject: [PATCH] Improve commenting around `IHasCombo` interfaces

Following discusion with smoogi IRL.
---
 osu.Game/Rulesets/Objects/Types/IHasCombo.cs       |  6 ++++++
 .../Rulesets/Objects/Types/IHasComboInformation.cs | 14 ++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/osu.Game/Rulesets/Objects/Types/IHasCombo.cs b/osu.Game/Rulesets/Objects/Types/IHasCombo.cs
index d1a4683a1d..5de5424bdc 100644
--- a/osu.Game/Rulesets/Objects/Types/IHasCombo.cs
+++ b/osu.Game/Rulesets/Objects/Types/IHasCombo.cs
@@ -16,6 +16,12 @@ namespace osu.Game.Rulesets.Objects.Types
         /// <summary>
         /// When starting a new combo, the offset of the new combo relative to the current one.
         /// </summary>
+        /// <remarks>
+        /// This is generally a setting provided by a beatmap creator to choreograph interesting colour patterns
+        /// which can only be achieved by skipping combo colours with per-hitobject level.
+        ///
+        /// It is exposed via <see cref="IHasComboInformation.ComboIndexWithOffsets"/>.
+        /// </remarks>
         int ComboOffset { get; }
     }
 }
diff --git a/osu.Game/Rulesets/Objects/Types/IHasComboInformation.cs b/osu.Game/Rulesets/Objects/Types/IHasComboInformation.cs
index d34e71021f..3aa68197ec 100644
--- a/osu.Game/Rulesets/Objects/Types/IHasComboInformation.cs
+++ b/osu.Game/Rulesets/Objects/Types/IHasComboInformation.cs
@@ -12,6 +12,9 @@ namespace osu.Game.Rulesets.Objects.Types
     /// </summary>
     public interface IHasComboInformation : IHasCombo
     {
+        /// <summary>
+        /// Bindable exposure of <see cref="IndexInCurrentCombo"/>.
+        /// </summary>
         Bindable<int> IndexInCurrentComboBindable { get; }
 
         /// <summary>
@@ -19,13 +22,21 @@ namespace osu.Game.Rulesets.Objects.Types
         /// </summary>
         int IndexInCurrentCombo { get; set; }
 
+        /// <summary>
+        /// Bindable exposure of <see cref="ComboIndex"/>.
+        /// </summary>
         Bindable<int> ComboIndexBindable { get; }
 
         /// <summary>
         /// The index of this combo in relation to the beatmap.
+        ///
+        /// In other words, this is incremented by 1 each time a <see cref="NewCombo"/> is reached.
         /// </summary>
         int ComboIndex { get; set; }
 
+        /// <summary>
+        /// Bindable exposure of <see cref="ComboIndexWithOffsets"/>.
+        /// </summary>
         Bindable<int> ComboIndexWithOffsetsBindable { get; }
 
         /// <summary>
@@ -39,6 +50,9 @@ namespace osu.Game.Rulesets.Objects.Types
         /// </summary>
         new bool NewCombo { get; set; }
 
+        /// <summary>
+        /// Bindable exposure of <see cref="LastInCombo"/>.
+        /// </summary>
         Bindable<bool> LastInComboBindable { get; }
 
         /// <summary>