From a974ed3d78b7768fd5c652c2988102396f83494d Mon Sep 17 00:00:00 2001
From: JoelCourtney <joel.e.courtney@gmail.com>
Date: Mon, 9 Sep 2024 15:41:49 -0700
Subject: [PATCH] Expand truncateList doc comment

---
 .../ammos/aerie/procedural/timeline/util/ListUtils.kt | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/util/ListUtils.kt b/procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/util/ListUtils.kt
index 1bcb897faf..266f768647 100644
--- a/procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/util/ListUtils.kt
+++ b/procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/util/ListUtils.kt
@@ -28,7 +28,16 @@ fun <V: IntervalLike<V>> preprocessList(list: List<V>, shouldCoalesce: (V.(V) ->
 fun <I: IntervalLike<I>> listCollector(list: List<I>, isSorted: Boolean = false, isSerial: Boolean = false) =
   { opts: CollectOptions -> truncateList(list, opts, isSorted, isSerial) }
 
-/** Eagerly truncates a list of timeline objects to known bounds. */
+/**
+ * Eagerly truncates a list of timeline objects to known bounds.
+ *
+ * `exploitSorted` and `isSerial` exist to provide extra information about the list, for performance optimization.
+ *
+ * @param list The list of [IntervalLike] objects to be sorted.
+ * @param opts Collect options, specifies the truncation bounds and behavior.
+ * @param exploitSorted Whether the start times of the intervals are sorted.
+ * @param isSerial Whether the list is "serial", i.e. sorted by start time AND non-overlapping.
+ */
 fun <I: IntervalLike<I>> truncateList(list: List<I>, opts: CollectOptions, exploitSorted: Boolean, isSerial: Boolean): List<I> =
     if (opts.bounds == Interval.MIN_MAX || list.isEmpty()) list
     else if (!exploitSorted) {