From da93849b8084b7bc0fb057704ee1a7a1606bf82f Mon Sep 17 00:00:00 2001
From: Dean Herbert <pe@ppy.sh>
Date: Tue, 25 Oct 2022 14:55:33 +0900
Subject: [PATCH] Rename some pieces and better document `SampleBankInfo`

---
 .../Objects/Legacy/ConvertHitObjectParser.cs  | 44 ++++++++++++++-----
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/osu.Game/Rulesets/Objects/Legacy/ConvertHitObjectParser.cs b/osu.Game/Rulesets/Objects/Legacy/ConvertHitObjectParser.cs
index b289299a63..930ee0448f 100644
--- a/osu.Game/Rulesets/Objects/Legacy/ConvertHitObjectParser.cs
+++ b/osu.Game/Rulesets/Objects/Legacy/ConvertHitObjectParser.cs
@@ -199,8 +199,8 @@ namespace osu.Game.Rulesets.Objects.Legacy
             if (stringAddBank == @"none")
                 stringAddBank = null;
 
-            bankInfo.Normal = stringBank;
-            bankInfo.Add = string.IsNullOrEmpty(stringAddBank) ? stringBank : stringAddBank;
+            bankInfo.BankForNormal = stringBank;
+            bankInfo.BankForAdditions = string.IsNullOrEmpty(stringAddBank) ? stringBank : stringAddBank;
 
             if (split.Length > 2)
                 bankInfo.CustomSampleBank = Parsing.ParseInt(split[2]);
@@ -447,32 +447,54 @@ namespace osu.Game.Rulesets.Objects.Legacy
 
             var soundTypes = new List<HitSampleInfo>
             {
-                new LegacyHitSampleInfo(HitSampleInfo.HIT_NORMAL, bankInfo.Normal, bankInfo.Volume, bankInfo.CustomSampleBank,
+                new LegacyHitSampleInfo(HitSampleInfo.HIT_NORMAL, bankInfo.BankForNormal, bankInfo.Volume, bankInfo.CustomSampleBank,
                     // if the sound type doesn't have the Normal flag set, attach it anyway as a layered sample.
                     // None also counts as a normal non-layered sample: https://osu.ppy.sh/help/wiki/osu!_File_Formats/Osu_(file_format)#hitsounds
                     type != LegacyHitSoundType.None && !type.HasFlagFast(LegacyHitSoundType.Normal))
             };
 
             if (type.HasFlagFast(LegacyHitSoundType.Finish))
-                soundTypes.Add(new LegacyHitSampleInfo(HitSampleInfo.HIT_FINISH, bankInfo.Add, bankInfo.Volume, bankInfo.CustomSampleBank));
+                soundTypes.Add(new LegacyHitSampleInfo(HitSampleInfo.HIT_FINISH, bankInfo.BankForAdditions, bankInfo.Volume, bankInfo.CustomSampleBank));
 
             if (type.HasFlagFast(LegacyHitSoundType.Whistle))
-                soundTypes.Add(new LegacyHitSampleInfo(HitSampleInfo.HIT_WHISTLE, bankInfo.Add, bankInfo.Volume, bankInfo.CustomSampleBank));
+                soundTypes.Add(new LegacyHitSampleInfo(HitSampleInfo.HIT_WHISTLE, bankInfo.BankForAdditions, bankInfo.Volume, bankInfo.CustomSampleBank));
 
             if (type.HasFlagFast(LegacyHitSoundType.Clap))
-                soundTypes.Add(new LegacyHitSampleInfo(HitSampleInfo.HIT_CLAP, bankInfo.Add, bankInfo.Volume, bankInfo.CustomSampleBank));
+                soundTypes.Add(new LegacyHitSampleInfo(HitSampleInfo.HIT_CLAP, bankInfo.BankForAdditions, bankInfo.Volume, bankInfo.CustomSampleBank));
 
             return soundTypes;
         }
 
         private class SampleBankInfo
         {
+            /// <summary>
+            /// An optional overriding filename which causes all bank/sample specifications to be ignored.
+            /// </summary>
             public string Filename;
 
-            public string Normal;
-            public string Add;
+            /// <summary>
+            /// The bank identifier to use for the base ("hitnormal") sample.
+            /// Transferred to <see cref="HitSampleInfo.Bank"/> when appropriate.
+            /// </summary>
+            public string BankForNormal;
+
+            /// <summary>
+            /// The bank identifier to use for additions ("hitwhistle", "hitfinish", "hitclap").
+            /// Transferred to <see cref="HitSampleInfo.Bank"/> when appropriate.
+            /// </summary>
+            public string BankForAdditions;
+
+            /// <summary>
+            /// Hit sample volume (0-100).
+            /// See <see cref="HitSampleInfo.Volume"/>.
+            /// </summary>
             public int Volume;
 
+            /// <summary>
+            /// The index of the custom sample bank. Is only used if 2 or above for "reasons".
+            /// This will add a suffix to lookups, allowing extended bank lookups (ie. "normal-hitnormal-2").
+            /// See <see cref="HitSampleInfo.Suffix"/>.
+            /// </summary>
             public int CustomSampleBank;
 
             public SampleBankInfo Clone() => (SampleBankInfo)MemberwiseClone();
@@ -503,7 +525,8 @@ namespace osu.Game.Rulesets.Objects.Legacy
             public sealed override HitSampleInfo With(Optional<string> newName = default, Optional<string?> newBank = default, Optional<string?> newSuffix = default, Optional<int> newVolume = default)
                 => With(newName, newBank, newVolume);
 
-            public virtual LegacyHitSampleInfo With(Optional<string> newName = default, Optional<string?> newBank = default, Optional<int> newVolume = default, Optional<int> newCustomSampleBank = default,
+            public virtual LegacyHitSampleInfo With(Optional<string> newName = default, Optional<string?> newBank = default, Optional<int> newVolume = default,
+                                                    Optional<int> newCustomSampleBank = default,
                                                     Optional<bool> newIsLayered = default)
                 => new LegacyHitSampleInfo(newName.GetOr(Name), newBank.GetOr(Bank), newVolume.GetOr(Volume), newCustomSampleBank.GetOr(CustomSampleBank), newIsLayered.GetOr(IsLayered));
 
@@ -537,7 +560,8 @@ namespace osu.Game.Rulesets.Objects.Legacy
                 Path.ChangeExtension(Filename, null)
             };
 
-            public sealed override LegacyHitSampleInfo With(Optional<string> newName = default, Optional<string?> newBank = default, Optional<int> newVolume = default, Optional<int> newCustomSampleBank = default,
+            public sealed override LegacyHitSampleInfo With(Optional<string> newName = default, Optional<string?> newBank = default, Optional<int> newVolume = default,
+                                                            Optional<int> newCustomSampleBank = default,
                                                             Optional<bool> newIsLayered = default)
                 => new FileHitSampleInfo(Filename, newVolume.GetOr(Volume));