From e598620c856984551ea09df275127b3b68264c82 Mon Sep 17 00:00:00 2001
From: voidedWarranties <hi+github@voidedxd.xyz>
Date: Sat, 30 Nov 2024 18:58:46 -0800
Subject: [PATCH 1/2] Document `CursorEffectContainer`

---
 osu.Framework/Graphics/Cursor/CursorEffectContainer.cs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs b/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs
index 5866b0e6f5..702755b491 100644
--- a/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs
+++ b/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs
@@ -12,6 +12,11 @@
 
 namespace osu.Framework.Graphics.Cursor
 {
+    /// <summary>
+    /// An abstract container type that handles positional input for many drawables of type <typeparamref name="TTarget"/>.
+    /// </summary>
+    /// <typeparam name="TSelf">The derived container type.</typeparam>
+    /// <typeparam name="TTarget">The target drawable type.</typeparam>
     public abstract partial class CursorEffectContainer<TSelf, TTarget> : Container
         where TSelf : CursorEffectContainer<TSelf, TTarget>
         where TTarget : class, IDrawable
@@ -112,6 +117,11 @@ private void findTargetChildren()
 
         private static readonly SlimReadOnlyListWrapper<TTarget> empty_list = new SlimReadOnlyListWrapper<TTarget>(new List<TTarget>(0));
 
+        /// <summary>
+        /// Returns currently hovered child drawables of type <typeparamref name="TTarget"/>.
+        /// </summary>
+        /// <returns>The list of candidate drawables in top-down order (see <see cref="InputManager.PositionalInputQueue"/>).</returns>
+        /// <remarks>Only drawables where <see cref="Drawable.HandlePositionalInput"/> is true are considered. When multiple <typeparamref name="TSelf"/> are nested, only the closest parent container receives the candidate.</remarks>
         protected SlimReadOnlyListWrapper<TTarget> FindTargets()
         {
             findTargetChildren();

From 8f2ca9a9db17ab73672a4ad013615b2da09c3a9c Mon Sep 17 00:00:00 2001
From: voidedWarranties <hi+github@voidedxd.xyz>
Date: Sat, 30 Nov 2024 18:58:56 -0800
Subject: [PATCH 2/2] Rename `nestedTtcChildDrawables`

---
 .../Graphics/Cursor/CursorEffectContainer.cs         | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs b/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs
index 702755b491..83285e9d3d 100644
--- a/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs
+++ b/osu.Framework/Graphics/Cursor/CursorEffectContainer.cs
@@ -32,14 +32,14 @@ protected override void LoadComplete()
         }
 
         private readonly HashSet<IDrawable> childDrawables = new HashSet<IDrawable>();
-        private readonly HashSet<IDrawable> nestedTtcChildDrawables = new HashSet<IDrawable>();
+        private readonly HashSet<IDrawable> nestedContainerChildDrawables = new HashSet<IDrawable>();
         private readonly List<IDrawable> newChildDrawables = new List<IDrawable>();
         private readonly List<TTarget> targetChildren = new List<TTarget>();
 
         private void findTargetChildren()
         {
             Debug.Assert(childDrawables.Count == 0, $"{nameof(childDrawables)} should be empty but has {childDrawables.Count} elements.");
-            Debug.Assert(nestedTtcChildDrawables.Count == 0, $"{nameof(nestedTtcChildDrawables)} should be empty but has {nestedTtcChildDrawables.Count} elements.");
+            Debug.Assert(nestedContainerChildDrawables.Count == 0, $"{nameof(nestedContainerChildDrawables)} should be empty but has {nestedContainerChildDrawables.Count} elements.");
             Debug.Assert(newChildDrawables.Count == 0, $"{nameof(newChildDrawables)} should be empty but has {newChildDrawables.Count} elements.");
             Debug.Assert(targetChildren.Count == 0, $"{nameof(targetChildren)} should be empty but has {targetChildren.Count} elements.");
 
@@ -100,14 +100,14 @@ private void findTargetChildren()
                 {
                     var d = newChildDrawables[j];
 
-                    if (d.Parent == this || (!(d.Parent is TSelf) && !nestedTtcChildDrawables.Contains(d.Parent)))
+                    if (d.Parent == this || (!(d.Parent is TSelf) && !nestedContainerChildDrawables.Contains(d.Parent)))
                         continue;
 
-                    nestedTtcChildDrawables.Add(d);
+                    nestedContainerChildDrawables.Add(d);
                 }
 
                 // Ignore drawables whose effects are managed by a nested effect container.
-                if (nestedTtcChildDrawables.Contains(candidate))
+                if (nestedContainerChildDrawables.Contains(candidate))
                     continue;
 
                 // We found a valid candidate; keep track of it
@@ -128,7 +128,7 @@ protected SlimReadOnlyListWrapper<TTarget> FindTargets()
 
             // Clean up
             childDrawables.Clear();
-            nestedTtcChildDrawables.Clear();
+            nestedContainerChildDrawables.Clear();
             newChildDrawables.Clear();
 
             if (targetChildren.Count == 0)