📚 docs(shuffle/_shuffle): Document function signatures.

Author: make-github-pseudonymous-again

src/api/shuffle.js

@@ -1,5 +1,13 @@
 import _shuffle from '../kernel/_shuffle.js';
 import sample from './sample.js';
 
+/**
+ * Shuffle array in-place between positions i and j-1 (inclusive).
+ * The other positions are left untouched.
+ * @function
+ * @param {Array} a The input array.
+ * @param {number} i The inclusive left bound.
+ * @param {number} j The non-inclusive right bound.
+ */
 const shuffle = _shuffle(sample);
 export default shuffle;

src/kernel/_shuffle.js

@@ -1,6 +1,20 @@
 /**
- * Shuffle array by sampling the complete array.
+ * Shuffle the array by sampling the entire array.
+ *
+ * @param {Function} sample The sample function.
+ * @return {Function} The shuffle function.
  */
+const _shuffle = (sample) => {
+	/**
+	 * Shuffle array in-place between positions i and j-1 (inclusive).
+	 * The other positions are left untouched.
+	 *
+	 * @param {Array} a The input array.
+	 * @param {number} i The inclusive left bound.
+	 * @param {number} j The non-inclusive right bound.
+	 */
+	const shuffle = (a, i, j) => sample(j - i, a, i, j);
+	return shuffle;
+};
 
-const _shuffle = (sample) => (a, i, j) => sample(j - i, a, i, j);
 export default _shuffle;