docs: improve JSDoc across spectra-processing functions

Add missing @returns/@param descriptions and normalize phrasing across matrix, reim, utils, x, xy, xyArray, and xyObject modules.

Author: lpatiny

src/matrix/matrixAbsoluteMedian.ts

@@ -4,7 +4,7 @@ import { xMedian } from '../x/index.ts';
 
 /**
  * Returns the median of the absolute matrix.
- * @param matrix
+ * @param matrix - input matrix.
  */
 export function matrixAbsoluteMedian(matrix: DoubleMatrix): number {
   const nbColumns = matrix[0].length;

src/matrix/matrixApplyNumericalEncoding.ts

@@ -4,9 +4,9 @@ import { matrixCreateEmpty } from './matrixCreateEmpty.ts';
 
 /**
  * Numerically encodes the strings in the matrix with an encoding dictionary.
- * @param matrixInitial - Original matrix before encoding.
- * @param dictionary - Dictionary against which to do the encoding.
- * @returns - Encoded matrix.
+ * @param matrixInitial - original matrix before encoding.
+ * @param dictionary - dictionary against which to do the encoding.
+ * @returns encoded matrix.
  */
 export function matrixApplyNumericalEncoding(
   matrixInitial: Array<Array<string | number>>,

src/matrix/matrixCheckRanges.ts

@@ -21,8 +21,8 @@ export interface SubmatrixBoundaries {
 
 /**
  * Checks if the specified submatrix boundaries are within the valid range of the given matrix.
- * @param matrix - The matrix to check the boundaries against.
- * @param boundaries - The boundaries of the submatrix.
+ * @param matrix - the matrix to check the boundaries against.
+ * @param boundaries - the boundaries of the submatrix.
  * @throws {RangeError} If any of the specified boundaries are out of the matrix's range.
  */
 export function matrixCheckRanges(

src/matrix/matrixCholeskySolver.ts

@@ -27,10 +27,10 @@ import type { NumberArray } from 'cheminfo-types';
 /**
  * Solves a system of linear equations using the Cholesky decomposition method.
  * It is a direct conversion to TS from {@link https://github.com/scijs/cholesky-solve}
- * @param nonZerosArray - The matrix in triplet form (array of arrays), where each sub-array contains three elements: row index, column index, and value.
- * @param dimension - The order of the matrix (number of rows/columns).
- * @param permutationEncoded - Optional permutation array. If provided, it will be used to permute the matrix.
- * @returns A function that takes a right-hand side vector `b` and returns the solution vector `x`, or `null` if the decomposition fails.
+ * @param nonZerosArray - the matrix in triplet form (array of arrays), where each sub-array contains three elements: row index, column index, and value.
+ * @param dimension - the order of the matrix (number of rows/columns).
+ * @param permutationEncoded - optional permutation array. If provided, it will be used to permute the matrix.
+ * @returns a function that takes a right-hand side vector `b` and returns the solution vector `x`, or `null` if the decomposition fails.
  */
 export function matrixCholeskySolver(
   nonZerosArray: NumberArray[],

src/matrix/matrixClone.ts

@@ -1,6 +1,6 @@
 /**
  * Clone a matrix.
- * @param matrix
+ * @param matrix - input matrix.
  */
 export function matrixClone<ValueType>(matrix: ValueType[][]): ValueType[][] {
   return matrix.map((row) => row.slice(0));

src/matrix/matrixCreateEmpty.ts

@@ -35,7 +35,7 @@ export interface MatrixCreateEmptyOptions<
 
 /**
  * Create a new matrix based on the size of the current one or by using specific dimensions.
- * @param options
+ * @param options - options.
  */
 export function matrixCreateEmpty<
   ArrayConstructorType extends NumberArrayConstructor = Float64ArrayConstructor,

src/matrix/matrixGetSubMatrix.ts

@@ -30,9 +30,9 @@ export interface MatrixGetSubMatrixOptions {
 /**
  * Get a subMatrix from matrix, the function checks if the subMatrix
  * lies within the dimensions of the matrix.
- * @param matrix - The original matrix from which the subMatrix will be extracted.
- * @param options - Options to define the subMatrix boundaries and duplication behavior.
- * @returns The subMatrix extracted from the original matrix.
+ * @param matrix - the original matrix from which the subMatrix will be extracted.
+ * @param options - options to define the subMatrix boundaries and duplication behavior.
+ * @returns the subMatrix extracted from the original matrix.
  */
 export function matrixGetSubMatrix(
   matrix: Float64Array[],

src/matrix/matrixHistogram.ts

@@ -56,7 +56,7 @@ export interface MatrixHistogramOptions {
  * Calculates a histogram of defined number of slots.
  * @param matrix - matrix [rows][cols].
  * @param options - options
- * @returns - Result of the histogram.
+ * @returns result of the histogram.
  */
 export function matrixHistogram(
   matrix: DoubleMatrix,

src/matrix/matrixMedian.ts

@@ -6,7 +6,7 @@ import { matrixToArray } from './matrixToArray.ts';
 
 /**
  * Returns the median of the matrix.
- * @param matrix
+ * @param matrix - input matrix.
  */
 export function matrixMedian(matrix: DoubleMatrix): number {
   return xMedian(matrixToArray(matrix));

src/matrix/matrixNoiseStandardDeviation.ts

@@ -8,8 +8,8 @@ import { matrixToArray } from './matrixToArray.ts';
  * Determine noise level using MAD https://en.wikipedia.org/wiki/Median_absolute_deviation
  * Constant to convert mad to sd calculated using https://www.wolframalpha.com/input?i=sqrt%282%29+inverse+erf%280.5%29
  * This assumes a gaussian distribution of the noise.
- * @param matrix
- * @returns Noise level corresponding to one standard deviation.
+ * @param matrix - input matrix.
+ * @returns noise level corresponding to one standard deviation.
  */
 export function matrixNoiseStandardDeviation(matrix: DoubleMatrix) {
   return xNoiseStandardDeviation(matrixToArray(matrix));