Rewrite/add comments.

osu.Game/Rulesets/Timing/LinearScrollingContainer.cs

@@ -7,8 +7,7 @@ using osu.Game.Rulesets.Timing;
 namespace osu.Game.Rulesets.Timing
 {
     /// <summary>
-    /// A <see cref="ScrollingContainer"/> which scrolls relative to the control point start time.
+    /// A <see cref="ScrollingContainer"/> which scrolls linearly relative to the <see cref="MultiplierControlPoint"/> start time.
-    /// This is the default <see cref="ScrollingContainer"/> returned by the base <see cref="SpeedAdjustmentContainer"/>.
     /// </summary>
     internal class LinearScrollingContainer : ScrollingContainer
     {

osu.Game/Rulesets/Timing/ScrollingContainer.cs

@@ -13,29 +13,13 @@ using osu.Game.Rulesets.Objects.Types;
 namespace osu.Game.Rulesets.Timing
 {
     /// <summary>
-    /// A collection of hit objects which scrolls within a <see cref="SpeedAdjustmentContainer"/>.
+    /// A container that scrolls relative to the current time. Will autosize to the total duration of all contained hit objects along the scrolling axes.
-    ///
-    /// <para>
-    /// This container handles the conversion between time and position through <see cref="Container{T}.RelativeChildSize"/> and
-    /// <see cref="Container{T}.RelativeChildOffset"/> such that hit objects added to this container should have time values set as their
-    /// positions/sizes to make proper use of this container.
-    /// </para>
-    ///
-    /// <para>
-    /// This container will auto-size to the total duration of the contained hit objects along the desired auto-sizing axes such that the resulting size
-    /// of this container will be a value representing the total duration of all contained hit objects.
-    /// </para>
-    ///
-    /// <para>
-    /// This container is and must always be relatively-sized and positioned to its such that the parent can utilise <see cref="Container{T}.RelativeChildSize"/>
-    /// and <see cref="Container{T}.RelativeChildOffset"/> to apply further time offsets to this collection of hit objects.
-    /// </para>
     /// </summary>
     public abstract class ScrollingContainer : Container<DrawableHitObject>
     {
         private readonly BindableDouble visibleTimeRange = new BindableDouble { Default = 1000 };
         /// <summary>
-        /// Gets or sets the range of time that is visible by the length of this container.
+        /// Gets or sets the range of time that is visible by the length of the scrolling axes.
         /// </summary>
         public BindableDouble VisibleTimeRange
         {
@@ -44,34 +28,17 @@ namespace osu.Game.Rulesets.Timing
         }
 
         /// <summary>
-        /// Axes through which this timing section scrolls. This is set by the <see cref="SpeedAdjustmentContainer"/>.
+        /// The axes through which this <see cref="ScrollingContainer"/> scrolls. This is set by the <see cref="SpeedAdjustmentContainer"/>.
         /// </summary>
         internal Axes ScrollingAxes;
 
         /// <summary>
-        /// The control point that provides the speed adjustments for this container. This is set by the <see cref="SpeedAdjustmentContainer"/>.
+        /// The control point that defines the speed adjustments for this container. This is set by the <see cref="SpeedAdjustmentContainer"/>.
         /// </summary>
         internal MultiplierControlPoint ControlPoint;
 
         private Cached<double> durationBacking;
 
-        protected override int Compare(Drawable x, Drawable y)
-        {
-            var xHitObject = x as DrawableHitObject;
-            var yHitObject = y as DrawableHitObject;
-
-            // If either of the two drawables are not hit objects, fall back to the base comparer
-            if (xHitObject?.HitObject == null || yHitObject?.HitObject == null)
-                return base.Compare(x, y);
-
-            // Compare by start time
-            int i = yHitObject.HitObject.StartTime.CompareTo(xHitObject.HitObject.StartTime);
-            if (i != 0)
-                return i;
-
-            return base.Compare(x, y);
-        }
-
         /// <summary>
         /// Creates a new <see cref="ScrollingContainer"/>.
         /// </summary>
@@ -106,13 +73,8 @@ namespace osu.Game.Rulesets.Timing
             if (baseDuration == 0)
                 baseDuration = 1;
 
-            // Scrolling ruleset hit objects typically have anchors+origins set to the hit object's start time, but if the hit object doesn't implement IHasEndTime and lies on the control point
+            // This container needs to resize such that it completely encloses the hit objects to avoid masking optimisations. This is done by converting the largest
-            // then the baseDuration above will be 0. This will cause problems with masking when it is further set as the value for Size in Update(). We _want_ the timing section bounds to
+            // absolutely-sized element along the scrolling axes and adding a corresponding duration value. This introduces a bit of error, but will never under-estimate.ion.
-            // completely enclose the hit object to avoid the masking optimisations.
-            //
-            // To do this we need to find a duration that corresponds to the absolute size of the element that extrudes beyond the timing section's bounds and add that to baseDuration.
-            // We can utilize the fact that the Size and RelativeChildSpace are 1:1, meaning that an change in duration for the timing section has no change to the hit object's positioning
-            // and simply find the largest absolutely-sized element in this timing section. This introduces a little bit of error, but will never under-estimate the duration.
 
             // Find the largest element that is absolutely-sized along ScrollingAxes
             float maxAbsoluteSize = Children.Where(c => (c.RelativeSizeAxes & ScrollingAxes) == 0)
@@ -129,7 +91,7 @@ namespace osu.Game.Rulesets.Timing
 
         /// <summary>
         /// The maximum duration of any one hit object inside this <see cref="ScrollingContainer"/>. This is calculated as the maximum
-        /// end time between all hit objects relative to this <see cref="ScrollingContainer"/>'s <see cref="MultiplierControlPoint.StartTime"/>.
+        /// duration of all hit objects relative to this <see cref="ScrollingContainer"/>'s <see cref="MultiplierControlPoint.StartTime"/>.
         /// </summary>
         public double Duration => durationBacking.IsValid ? durationBacking : (durationBacking.Value = computeDuration());
 
@@ -137,7 +99,7 @@ namespace osu.Game.Rulesets.Timing
         {
             base.Update();
 
-            // We want our size and position-space along ScrollingAxes to span our duration to completely enclose all the hit objects
+            // We want our size and position-space along the scrolling axes to span our duration to completely enclose all the hit objects
             Size = new Vector2((ScrollingAxes & Axes.X) > 0 ? (float)Duration : Size.X, (ScrollingAxes & Axes.Y) > 0 ? (float)Duration : Size.Y);
             // And we need to make sure the hit object's position-space doesn't change due to our resizing
             RelativeChildSize = Size;

osu.Game/Rulesets/Timing/SpeedAdjustmentContainer.cs

@@ -11,19 +11,14 @@ using OpenTK;
 namespace osu.Game.Rulesets.Timing
 {
     /// <summary>
-    /// A container for hit objects which applies applies the speed adjustments defined by the properties of a <see cref="Timing.MultiplierControlPoint"/>
+    /// A container that provides the speed adjustments defined by <see cref="MultiplierControlPoint"/>s to affect the scroll speed
-    /// to affect the scroll speed of the contained <see cref="ScrollingContainer"/>.
+    /// of container <see cref="DrawableHitObject"/>s.
-    ///
-    /// <para>
-    /// This container must always be relatively-sized to its parent to provide the speed adjustments. This container will provide the speed adjustments
-    /// by modifying its size while maintaining a constant <see cref="Container{T}.RelativeChildSize"/> for its children
-    /// </para>
     /// </summary>
     public class SpeedAdjustmentContainer : Container<DrawableHitObject>
     {
         private readonly Bindable<double> visibleTimeRange = new Bindable<double> { Default = 1000 };
         /// <summary>
-        /// Gets or sets the range of time that is visible by the length of this container.
+        /// Gets or sets the range of time that is visible by the length of the scrolling axes.
         /// </summary>
         public Bindable<double> VisibleTimeRange
         {
@@ -35,10 +30,13 @@ namespace osu.Game.Rulesets.Timing
         private Container<DrawableHitObject> content;
 
         /// <summary>
-        /// Axes which the content of this container will scroll through.
+        /// The axes which the content of this container will scroll through.
         /// </summary>
         public Axes ScrollingAxes { get; internal set; }
 
+        /// <summary>
+        /// The <see cref="MultiplierControlPoint"/> that defines the speed adjustments.
+        /// </summary>
         public readonly MultiplierControlPoint ControlPoint;
 
         private ScrollingContainer scrollingContainer;
@@ -46,11 +44,10 @@ namespace osu.Game.Rulesets.Timing
         /// <summary>
         /// Creates a new <see cref="SpeedAdjustmentContainer"/>.
         /// </summary>
-        /// <param name="controlPoint">The <see cref="MultiplierControlPoint"/> which provides the speed adjustments for this container.</param>
+        /// <param name="controlPoint">The <see cref="MultiplierControlPoint"/> that defines the speed adjustments.</param>
         public SpeedAdjustmentContainer(MultiplierControlPoint controlPoint)
         {
             ControlPoint = controlPoint;
-
             RelativeSizeAxes = Axes.Both;
         }
 
@@ -93,17 +90,17 @@ namespace osu.Game.Rulesets.Timing
         }
 
         /// <summary>
-        /// Whether this speed adjustment can contain a hit object. This is true if the hit object occurs after this speed adjustment with respect to time.
+        /// Whether a <see cref="DrawableHitObject"/> falls within this <see cref="SpeedAdjustmentContainer"/>s affecting timespan.
         /// </summary>
         public bool CanContain(DrawableHitObject hitObject) => CanContain(hitObject.HitObject.StartTime);
 
         /// <summary>
-        /// Whether this speed adjustment can contain an object placed at a time value. This is true if the time occurs after this speed adjustment.
+        /// Whether a point in time falls within this <see cref="SpeedAdjustmentContainer"/>s affecting timespan.
         /// </summary>
         public bool CanContain(double startTime) => ControlPoint.StartTime <= startTime;
 
         /// <summary>
-        /// Creates the container which contains a collection of hit objects and scrolls through this SpeedAdjustmentContainer.
+        /// Creates the <see cref="ScrollingContainer"/> which contains the scrolling <see cref="DrawableHitObject"/>s of this container.
         /// </summary>
         /// <returns>The <see cref="ScrollingContainer"/>.</returns>
         protected virtual ScrollingContainer CreateScrollingContainer() => new LinearScrollingContainer(ScrollingAxes, ControlPoint);

osu.Game/Rulesets/UI/ScrollingHitRenderer.cs

@@ -17,14 +17,19 @@ using osu.Game.Rulesets.Timing;
 namespace osu.Game.Rulesets.UI
 {
     /// <summary>
-    /// A type of <see cref="HitRenderer{TObject, TJudgement}"/> that exposes <see cref="MultiplierControlPoint"/>s to be used
+    /// A type of <see cref="HitRenderer{TPlayfield, TObject, TJudgement}"/> that supports a <see cref="ScrollingPlayfield{TObject, TJudgement}"/>.
-    /// in <see cref="SpeedAdjustmentCollection"/>s.
+    /// <see cref="HitObject"/>s inside this <see cref="HitRenderer{TPlayfield, TObject, TJudgement}"/> will scroll within the playfield.
     /// </summary>
     public abstract class ScrollingHitRenderer<TPlayfield, TObject, TJudgement> : HitRenderer<TPlayfield, TObject, TJudgement>
         where TObject : HitObject
         where TJudgement : Judgement
         where TPlayfield : ScrollingPlayfield<TObject, TJudgement>
     {
+        /// <summary>
+        /// Provides the default <see cref="MultiplierControlPoint"/>s that adjust the scrolling rate of <see cref="HitObject"/>s
+        /// inside this <see cref="HitRenderer{TPlayfield, TObject, TJudgement}"/>.
+        /// </summary>
+        /// <returns></returns>
         protected readonly SortedList<MultiplierControlPoint> DefaultControlPoints = new SortedList<MultiplierControlPoint>(Comparer<MultiplierControlPoint>.Default);
 
         protected ScrollingHitRenderer(WorkingBeatmap beatmap, bool isForCurrentRuleset)
@@ -87,15 +92,16 @@ namespace osu.Game.Rulesets.UI
 
             DefaultControlPoints.AddRange(timingChanges);
 
+            // If we have no control points, add a default one
             if (DefaultControlPoints.Count == 0)
                 DefaultControlPoints.Add(new MultiplierControlPoint());
         }
 
         /// <summary>
-        /// Generates a control point with the default timing change/difficulty change from the beatmap at a time.
+        /// Generates a <see cref="MultiplierControlPoint"/> with the default timing change/difficulty change from the beatmap at a time.
         /// </summary>
         /// <param name="time">The time to create the control point at.</param>
-        /// <returns>The <see cref="MultiplierControlPoint"/> at <paramref name="time"/>.</returns>
+        /// <returns>The default <see cref="MultiplierControlPoint"/> at <paramref name="time"/>.</returns>
         public MultiplierControlPoint CreateControlPointAt(double time)
         {
             if (DefaultControlPoints.Count == 0)
@@ -108,6 +114,11 @@ namespace osu.Game.Rulesets.UI
             return new MultiplierControlPoint(time, DefaultControlPoints[index].DeepClone());
         }
 
+        /// <summary>
+        /// Creates a <see cref="SpeedAdjustmentContainer"/> that facilitates the movement of hit objects.
+        /// </summary>
+        /// <param name="controlPoint">The <see cref="MultiplierControlPoint"/> that provides the speed adjustments for the hitobjects.</param>
+        /// <returns>The <see cref="SpeedAdjustmentContainer"/>.</returns>
         protected virtual SpeedAdjustmentContainer CreateSpeedAdjustmentContainer(MultiplierControlPoint controlPoint) => new SpeedAdjustmentContainer(controlPoint);
     }
 }

osu.Game/Rulesets/UI/ScrollingPlayfield.cs

@@ -15,17 +15,33 @@ using osu.Game.Rulesets.Timing;
 
 namespace osu.Game.Rulesets.UI
 {
+    /// <summary>
+    /// A type of <see cref="Playfield{TObject, TJudgement}"/> specialized towards scrolling <see cref="DrawableHitObjects"/>.
+    /// </summary>
     public class ScrollingPlayfield<TObject, TJudgement> : Playfield<TObject, TJudgement>
         where TObject : HitObject
         where TJudgement : Judgement
     {
+        /// <summary>
+        /// The default span of time visible by the length of the scrolling axes.
+        /// This is clamped between <see cref="time_span_min"/> and <see cref="time_span_max"/>.
+        /// </summary>
         private const double time_span_default = 1500;
+        /// <summary>
+        /// The minimum span of time that may be visible by the length of the scrolling axes.
+        /// </summary>
         private const double time_span_min = 50;
+        /// <summary>
+        /// The maximum span of time that may be visible by the length of the scrolling axes.
+        /// </summary>
         private const double time_span_max = 10000;
+        /// <summary>
+        /// The step increase/decrease of the span of time visible by the length of the scrolling axes.
+        /// </summary>
         private const double time_span_step = 50;
 
         /// <summary>
-        /// Gets or sets the range of time that is visible by the length of this playfield the scrolling axis direction.
+        /// Gets or sets the range of time that is visible by the length of the scrolling axes.
         /// For example, only hit objects with start time less than or equal to 1000 will be visible with <see cref="VisibleTimeRange"/> = 1000.
         /// </summary>
         private readonly BindableDouble visibleTimeRange = new BindableDouble(time_span_default)
@@ -35,14 +51,26 @@ namespace osu.Game.Rulesets.UI
             MaxValue = time_span_max
         };
 
+        /// <summary>
+        /// The span of time visible by the length of the scrolling axes.
+        /// </summary>
+        /// <returns></returns>
         public BindableDouble VisibleTimeRange
         {
             get { return visibleTimeRange; }
             set { visibleTimeRange.BindTo(value); }
         }
 
+        /// <summary>
+        /// The container that contains the <see cref="SpeedAdjustmentContainer"/>s and <see cref="DrawableHitObject"/>s.
+        /// </summary>
         internal new readonly ScrollingHitObjectContainer HitObjects;
 
+        /// <summary>
+        /// Creates a new <see cref="ScrollingPlayfield{TObject, TJudgement}"/>.
+        /// </summary>
+        /// <param name="scrollingAxes">The axes on which <see cref="DrawableHitObject"/>s in this container should scroll.</param>
+        /// <param name="customWidth">Whether we want our internal coordinate system to be scaled to a specified width</param>
         protected ScrollingPlayfield(Axes scrollingAxes, float? customWidth = null)
             : base(customWidth)
         {
@@ -54,8 +82,16 @@ namespace osu.Game.Rulesets.UI
         }
 
         private List<ScrollingPlayfield<TObject, TJudgement>> nestedPlayfields;
+        /// <summary>
+        /// All the <see cref="ScrollingPlayfield{TObject, TJudgement}"/>s nested inside this playfield.
+        /// </summary>
         public IEnumerable<ScrollingPlayfield<TObject, TJudgement>> NestedPlayfields => nestedPlayfields;
 
+        /// <summary>
+        /// Adds a <see cref="ScrollingPlayfield{TObject, TJudgement}"/> to this playfield. The nested <see cref="ScrollingPlayfield{TObject, TJudgement}"/>
+        /// will be given all of the same speed adjustments as this playfield.
+        /// </summary>
+        /// <param name="otherPlayfield">The <see cref="ScrollingPlayfield{TObject, TJudgement}"/> to add.</param>
         protected void AddNested(ScrollingPlayfield<TObject, TJudgement> otherPlayfield)
         {
             if (nestedPlayfields == null)
@@ -104,19 +140,13 @@ namespace osu.Game.Rulesets.UI
         }
 
         /// <summary>
-        /// A collection of <see cref="SpeedAdjustmentContainer"/>s.
+        /// A container that provides the foundation for sorting <see cref="DrawableHitObject"/>s into <see cref="SpeedAdjustmentContainer"/>s.
-        ///
-        /// <para>
-        /// This container redirects any <see cref="DrawableHitObject"/>'s added to it to the <see cref="SpeedAdjustmentContainer"/>
-        /// which provides the speed adjustment active at the start time of the hit object. Furthermore, this container provides the
-        /// necessary <see cref="VisibleTimeRange"/> for the contained <see cref="SpeedAdjustmentContainer"/>s.
-        /// </para>
         /// </summary>
         internal class ScrollingHitObjectContainer : HitObjectContainer<DrawableHitObject<TObject, TJudgement>>
         {
             private readonly BindableDouble visibleTimeRange = new BindableDouble { Default = 1000 };
             /// <summary>
-            /// Gets or sets the range of time that is visible by the length of this container.
+            /// Gets or sets the range of time that is visible by the length of the scrolling axes.
             /// For example, only hit objects with start time less than or equal to 1000 will be visible with <see cref="VisibleTimeRange"/> = 1000.
             /// </summary>
             public Bindable<double> VisibleTimeRange
@@ -126,9 +156,6 @@ namespace osu.Game.Rulesets.UI
             }
 
             protected override Container<DrawableHitObject<TObject, TJudgement>> Content => content;
-            /// <summary>
-            /// The following is never used - it only exists for the purpose of being able to use AddInternal below.
-            /// </summary>
             private Container<DrawableHitObject<TObject, TJudgement>> content;
 
             /// <summary>
@@ -146,9 +173,14 @@ namespace osu.Game.Rulesets.UI
             {
                 this.scrollingAxes = scrollingAxes;
 
+                // The following is never used - it only exists for the purpose of being able to use AddInternal below.
                 content = new Container<DrawableHitObject<TObject, TJudgement>>();
             }
 
+            /// <summary>
+            /// Adds a <see cref="SpeedAdjustmentContainer"/> to this container.
+            /// </summary>
+            /// <param name="speedAdjustment">The <see cref="SpeedAdjustmentContainer"/>.</param>
             public void AddSpeedAdjustment(SpeedAdjustmentContainer speedAdjustment)
             {
                 speedAdjustment.VisibleTimeRange.BindTo(VisibleTimeRange);
@@ -157,8 +189,8 @@ namespace osu.Game.Rulesets.UI
             }
 
             /// <summary>
-            /// Adds a hit object to this <see cref="ScrollingHitObjectContainer"/>. The hit objects will be kept in a queue
+            /// Adds a hit object to this <see cref="ScrollingHitObjectContainer"/>. The hit objects will be queued to be processed
-            /// and will be processed when new <see cref="SpeedAdjustmentContainer"/>s are added to this <see cref="ScrollingHitObjectContainer"/>.
+            /// new <see cref="SpeedAdjustmentContainer"/>s are added to this <see cref="ScrollingHitObjectContainer"/>.
             /// </summary>
             /// <param name="hitObject">The hit object to add.</param>
             public override void Add(DrawableHitObject<TObject, TJudgement> hitObject)