refactor(types) add type coverage & docs for binarySearchBounds.js

lib/util/binarySearchBounds.js

@@ -8,6 +8,28 @@
 /* cspell:disable-next-line */
 // Refactor: Peter Somogyvari @petermetz
 
+/** @typedef {">=" | "<=" | "<" | ">" | "-" } BinarySearchPredicate */
+/** @typedef {"GE" | "GT" | "LT" | "LE" | "EQ" } SearchPredicateSuffix */
+
+/**
+ * Helper function for compiling binary search functions.
+ *
+ * The generated code uses a while loop to repeatedly divide the search interval
+ * in half until the desired element is found, or the search interval is empty.
+ *
+ * The following is an example of a generated function for calling `compileSearch("myFunc", ">=", true, ["value"], false)`:
+ *
+ * ```js
+ * function myFunc(a,l,h,value){var i=l-1;while(l<=h){var m=(l+h)>>>1,x=a[m];if(>=){i=m;l=m+1}else{h=m-1}}return i};
+ * ```
+ *
+ * @param {string} funcName The name of the function to be compiled.
+ * @param {string} predicate The predicate / comparison operator to be used in the binary search.
+ * @param {boolean} reversed Whether the search should be reversed.
+ * @param {string[]} extraArgs Extra arguments to be passed to the function.
+ * @param {boolean=} earlyOut Whether the search should return as soon as a match is found.
+ * @returns {string} The compiled binary search function.
+ */
 const compileSearch = (funcName, predicate, reversed, extraArgs, earlyOut) => {
 	const code = [
 		"function ",
@@ -43,6 +65,18 @@ const compileSearch = (funcName, predicate, reversed, extraArgs, earlyOut) => {
 	return code.join("");
 };
 
+/**
+ * This helper functions generate code for two binary search functions:
+ * A(): Performs a binary search on an array using the comparison operator specified.
+ * P(): Performs a binary search on an array using a _custom comparison function_
+ * `c(x,y)` **and** comparison operator specified by `predicate`.
+ *
+ * @param {BinarySearchPredicate} predicate The predicate / comparison operator to be used in the binary search.
+ * @param {boolean} reversed Whether the search should be reversed.
+ * @param {SearchPredicateSuffix} suffix The suffix to be used in the function name.
+ * @param {boolean=} earlyOut Whether the search should return as soon as a match is found.
+ * @returns {function} The compiled binary search function.
+ */
 const compileBoundsSearch = (predicate, reversed, suffix, earlyOut) => {
 	const arg1 = compileSearch(
 		"A",
@@ -77,6 +111,21 @@ return dispatchBinarySearch";
 	return result();
 };
 
+/**
+ * These functions are used to perform binary searches on arrays.
+ *
+ * @example
+ * ```js
+ * const { gt, le} = require("./binarySearchBounds");
+ * const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+ *
+ * // Find the index of the first element greater than 5
+ * const index1 = gt(arr, 5); // index1 === 3
+ *
+ * // Find the index of the first element less than or equal to 5
+ * const index2 = le(arr, 5); // index2 === 4
+ * ```
+ */
 module.exports = {
 	ge: compileBoundsSearch(">=", false, "GE"),
 	gt: compileBoundsSearch(">", false, "GT"),