From 4236dd826d7a834c7dc9056bfbfaf2dfa0d99e6b Mon Sep 17 00:00:00 2001
From: smoogipoo <smoogipoo@smgi.me>
Date: Fri, 13 Nov 2020 14:57:09 +0900
Subject: [PATCH] Improve documentation and make abstract again

---
 .../Visual/Gameplay/TestScenePoolingRuleset.cs      |  2 ++
 osu.Game/Rulesets/UI/DrawableRuleset.cs             | 13 +++++++++----
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/osu.Game.Tests/Visual/Gameplay/TestScenePoolingRuleset.cs b/osu.Game.Tests/Visual/Gameplay/TestScenePoolingRuleset.cs
index c3ae753eae..242eaf7b7d 100644
--- a/osu.Game.Tests/Visual/Gameplay/TestScenePoolingRuleset.cs
+++ b/osu.Game.Tests/Visual/Gameplay/TestScenePoolingRuleset.cs
@@ -142,6 +142,8 @@ private void load()
 
             protected override HitObjectLifetimeEntry CreateLifetimeEntry(TestHitObject hitObject) => new TestHitObjectLifetimeEntry(hitObject);
 
+            public override DrawableHitObject<TestHitObject> CreateDrawableRepresentation(TestHitObject h) => null;
+
             protected override PassThroughInputManager CreateInputManager() => new PassThroughInputManager();
 
             protected override Playfield CreatePlayfield() => new TestPlayfield();
diff --git a/osu.Game/Rulesets/UI/DrawableRuleset.cs b/osu.Game/Rulesets/UI/DrawableRuleset.cs
index 0429936d8e..c912348604 100644
--- a/osu.Game/Rulesets/UI/DrawableRuleset.cs
+++ b/osu.Game/Rulesets/UI/DrawableRuleset.cs
@@ -324,11 +324,16 @@ public override void SetReplayScore(Score replayScore)
         }
 
         /// <summary>
-        /// Creates a DrawableHitObject from a HitObject.
+        /// Creates a <see cref="DrawableHitObject{TObject}"/> to represent a <see cref="HitObject"/>.
         /// </summary>
-        /// <param name="h">The HitObject to make drawable.</param>
-        /// <returns>The DrawableHitObject.</returns>
-        public virtual DrawableHitObject<TObject> CreateDrawableRepresentation(TObject h) => null;
+        /// <remarks>
+        /// If this method returns <c>null</c>, then this <see cref="DrawableRuleset"/> will assume the requested <see cref="HitObject"/> type is being pooled,
+        /// and will instead attempt to retrieve the <see cref="DrawableHitObject"/>s at the point they should become alive via pools registered through
+        /// <see cref="DrawableRuleset.RegisterPool{TObject, TDrawable}(int, int?)"/> or  <see cref="DrawableRuleset.RegisterPool{TObject, TDrawable}(DrawablePool{TDrawable})"/>.
+        /// </remarks>
+        /// <param name="h">The <see cref="HitObject"/> to represent.</param>
+        /// <returns>The representing <see cref="DrawableHitObject{TObject}"/>.</returns>
+        public abstract DrawableHitObject<TObject> CreateDrawableRepresentation(TObject h);
 
         public void Attach(KeyCounterDisplay keyCounter) =>
             (KeyBindingInputManager as ICanAttachKeyCounter)?.Attach(keyCounter);