refactor: Improve documentation and test descriptions for binary search functions

Author: Henry8192

src/typings/decoders.ts

@@ -128,7 +128,7 @@ interface Decoder {
      * behaviour.
      *
      * @param timestamp
-     * @return The index of the log event L.
+     * @return The index of the log event L, or null if there are no log events.
      */
     findNearestLogEventByTimestamp(timestamp: number): Nullable<number>;
 }

src/utils/math.ts

@@ -28,11 +28,12 @@ const getChunkNum =
  * `upperboundValue`. If all elements in the collection are greater than `upperboundValue`, return
  * the first index of the collection (i.e., `0`).
  *
- * @param get
+ * @param get Function provided to access elements in the collection by index.
  * @param lowIdx
  * @param highIdx
  * @param upperboundValue
- * @return
+ * @return The index of the last element less than or equal to `upperboundValue`,`0` if all elements
+ * are greater, or `null` if the collection is empty or the indices are invalid.
  */
 const upperBoundBinarySearch = <T>(
     get: (index: number) => T,

test/utils/math.test.ts

@@ -24,7 +24,7 @@ describe("clamp", () => {
     });
 
     test(
-        "returns the upper boundary when the upper boundary is less than the lower boundary",
+        "returns the upper boundary if the upper boundary is less than the lower boundary",
         () => {
             expect(clamp(5, 10, 1)).toBe(1);
         }
@@ -56,48 +56,48 @@ describe("upperBoundBinarySearch", () => {
     const emptyArray: number[] = [];
     const singleElementArray = [3];
     const array = [-5, -3, 0, 1, 1, 8, 8, 8, 100];
-    test("returns null for empty collection with fake highIdx", () => {
+    test("returns null if collection is empty with lowIdx < highIdx", () => {
         const result = upperBoundBinarySearch((idx) => emptyArray[idx], 0, 1, 5);
         expect(result).toBeNull();
     });
-    test("returns null for empty collection with valid highIdx", () => {
+    test("returns null if collection is empty with highIdx < lowIdx", () => {
         const result = upperBoundBinarySearch((idx) => emptyArray[idx], 0, -1, 5);
         expect(result).toBeNull();
     });
-    test("returns the first index for upperboundValue < all elements in array", () => {
+    test("returns the first index if upperboundValue < all elements in array", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, -10);
         expect(result).toBe(0);
     });
-    test("returns the first index for upperboundValue < element in singleElementArray", () => {
+    test("returns the first index if upperboundValue < element in singleElementArray", () => {
         const result = upperBoundBinarySearch((idx) => singleElementArray[idx], 0, 0, -10);
         expect(result).toBe(0);
     });
-    test("returns the last index for upperboundValue > all elements in array", () => {
+    test("returns the last index if upperboundValue > all elements in array", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, 200);
         expect(result).toBe(array.length - 1);
     });
-    test("returns the last index for upperboundValue > element in singleElementArray", () => {
+    test("returns the last index if upperboundValue > element in singleElementArray", () => {
         const result = upperBoundBinarySearch((idx) => singleElementArray[idx], 0, 0, 200);
         expect(result).toBe(0);
     });
-    test("returns the index for upperboundValue doesn't exactly match any elements", () => {
+    test("returns the correct index if upperboundValue doesn't match any elements", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, 2);
         expect(result).toBe(4);
     });
-    test("returns the index for upperboundValue matches a unique element", () => {
+    test("returns the correct index if upperboundValue matches a unique element", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, 0);
         expect(result).toBe(2);
     });
-    test("returns the index for upperboundValue matches a duplicated element", () => {
+    test("returns the last matched index if upperboundValue matches a duplicated element", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, 8);
         expect(result).toBe(7);
     });
-    test("returns the first element index", () => {
+    test("returns index 0 if upperboundValue matches the first element", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, -5);
         expect(result).toBe(0);
     });
-    test("returns the last element index", () => {
+    test("returns the last index if upperboundValue matches the last element", () => {
         const result = upperBoundBinarySearch((idx) => array[idx], 0, array.length - 1, 100);
-        expect(result).toBe(8);
+        expect(result).toBe(array.length - 1);
     });
 });