docs(array-utils): tweaks to docs and annotations

Author: z3dev

packages/array-utils/src/flatten.js

@@ -1,9 +1,14 @@
 /**
  * Flatten the given array into a single array of elements.
+ *
  * The given array can be composed of multiple depths of objects and or arrays.
+ *
  * @param {Array} array - array to flatten
  * @returns {Array} a flat array with a single list of elements
+ *
  * @alias module:array-utils.flatten
+ * @function
+ *
  * @example
  * const flat = flatten([[1], [2, 3, [4, 5]], 6]) // returns [1, 2, 3, 4, 5, 6]
  */

packages/array-utils/src/fnNumberSort.js

@@ -1,9 +1,13 @@
 /**
  * Compare function for sorting arrays of numbers.
+ *
  * @param {number} a - first number
  * @param {number} b - second number
  * @return {number} result of a - b
+ *
  * @alias module:array-utils.fnNumberSort
+ * @function
+ *
  * @example
  * const numbers = [2, 1, 4, 3, 6, 5, 8, 7, 9, 0]
  * const sorted = numbers.sort(fnNumberSort)

packages/array-utils/src/head.js

@@ -1,8 +1,12 @@
 /**
  * Return the first element of the given array.
+ *
  * @param {*} array - anything
  * @returns {*} first element of the array, or undefined
+ *
  * @alias module:array-utils.head
+ * @function
+ *
  * @example
  * let element = head([1, 2])
  */

packages/array-utils/src/insertSorted.js

@@ -1,9 +1,13 @@
 /**
  * Insert the given element into the give array using the compareFunction.
+ *
  * @param {Array} array - array in which to insert
  * @param {*} element - element to insert into the array
  * @param {Function} compareFunction - a function that defines the sort order of elements
+ *
  * @alias module:array-utils.insertSorted
+ * @function
+ *
  * @example
  * const numbers = [1, 5]
  * const result = insertSorted(numbers, 3, fnNumberSort)

packages/array-utils/src/nth.js

@@ -1,9 +1,13 @@
 /**
  * Return the Nth element of the given array.
+ *
  * @param {*} array - anything
  * @param {number} index - index of the element to return
  * @returns {*} Nth element of the array, or undefined
+ *
  * @alias module:array-utils.nth
+ * @function
+ *
  * @example
  * let value = nth([1], 2) // undefined
  * let value = nth([1, 2, 3, 4, 5], 3) // 4

packages/array-utils/src/padToLength.js

@@ -1,11 +1,16 @@
 /**
  * Build an array of the given target length from an existing array and a padding value.
+ *
  * If the array is already larger than the target length, it will not be shortened.
+ *
  * @param {Array} anArray - the source array to copy into the result.
  * @param {*} padding - the value to add to the new array to reach the desired length.
  * @param {number} targetLength - The desired length of the returned array.
  * @returns {Array} an array with at least 'target length" elements
+ *
  * @alias module:array-utils.padToLength
+ * @function
+ *
  * @example
  * const srcArray = [2, 3, 4]
  * const paddedArray = padToLength(srcArray, 0, 5)

packages/array-utils/src/toArray.js

@@ -1,8 +1,12 @@
 /**
  * Convert the given array to an array if not already an array.
+ *
  * @param {*} array - anything
  * @returns {Array} an array
+ *
  * @alias module:array-utils.toArray
+ * @function
+ *
  * @example
  * const array = toArray(1) // [1]
  */