docs: improve JSDoc across spectra-processing functions

src/matrix/matrixAbsoluteMedian.ts

@@ -2,9 +2,9 @@
 
 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

@@ -33,9 +33,9 @@
   ArrayConstructor?: ArrayConstructorType;
 }
 
 /**
  * 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

@@ -4,9 +4,9 @@
 
 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));

src/matrix/matrixNumericalDecoding.ts

@@ -2,9 +2,9 @@ import { matrixClone } from './matrixClone.ts';
 
 /**
  * Numerically decodes the matrix using the dictionary.
- * @param matrixInitial
- * @param dictionary - dictionary against which to do the encoding
- * @returns - decoded matrix
+ * @param matrixInitial - original matrix to decode.
+ * @param dictionary - dictionary against which to do the encoding.
+ * @returns decoded matrix.
  */
 export function matrixNumericalDecoding(
   matrixInitial: number[][],

src/matrix/matrixSetSubMatrix.ts

@@ -9,7 +9,7 @@ import { matrixCheckRanges } from './matrixCheckRanges.ts';
  * @param subMatrix - matrix with equal or less size than matrix.
  * @param startRow - row index in matrix for the first row in subMatrix.
  * @param startColumn - column index in matrix for the first column in subMatrix.
- * @returns The modified `matrix`.
+ * @returns the modified `matrix`.
  */
 export function matrixSetSubMatrix(
   matrix: DoubleMatrix,

src/matrix/matrixToArray.ts

@@ -4,7 +4,7 @@ import { matrixCheck } from './matrixCheck.ts';
 
 /**
  * Convert a matrix to a flat Float64Array.
- * @param matrix
+ * @param matrix - input matrix.
  */
 export function matrixToArray(matrix: DoubleMatrix): Float64Array<ArrayBuffer> {
   matrixCheck(matrix);

src/matrix/matrixZPivotRescale.ts

@@ -27,7 +27,7 @@ export interface MatrixZPivotRescaleOptions<
 /**
  * Rescale a matrix around 0 taking into account the absolute max value.
  * @param matrix - matrix [rows][cols].
- * @param options - Options.
+ * @param options - options.
  */
 export function matrixZPivotRescale<
   ArrayConstructorType extends NumberArrayConstructor = Float64ArrayConstructor,

src/matrix/matrixZRescale.ts

@@ -33,7 +33,7 @@ export interface MatrixZRescaleOptions<
 /**
  * Rescale a matrix between min and max values.
  * @param matrix - matrix [rows][cols].
- * @param options - Options.
+ * @param options - options.
  */
 export function matrixZRescale<
   ArrayConstructorType extends DoubleArrayConstructor = Float64ArrayConstructor,

src/matrix/matrixZRescalePerColumn.ts

@@ -19,7 +19,7 @@ export interface MatrixZRescalePerColumnOptions {
 /**
  * Rescale the matrix per column for which we get the min and max values.
  * @param matrix - matrix [rows][cols].
- * @param options - Options.
+ * @param options - options.
  */
 export function matrixZRescalePerColumn(
   matrix: DoubleMatrix,

src/reim/reimAbsolute.ts

@@ -4,10 +4,10 @@ import type { DataReIm } from '../types/index.ts';
 
 /**
  * Calculates reimAbsolute value of a complex spectrum.
- * @param data - complex spectrum
- * @param options
- * @param options.output
- * @returns - reimAbsolute value
+ * @param data - complex spectrum.
+ * @param options - options.
+ * @param options.output - optional output array.
+ * @returns absolute value array.
  */
 export function reimAbsolute(
   data: DataReIm,

src/reim/reimAutoPhaseCorrection.ts

@@ -165,11 +165,11 @@ interface AutoPhaseRegionResult {
 }
 
 /**
- * AutoPhaseRegion.
- * @param re - Array of Number.
- * @param im - Array of Number.
- * @param x0 - Number.
- * @returns Region.
+ * Finds the best phase angle for a region by minimizing the negative area.
+ * @param re - array of number.
+ * @param im - array of number.
+ * @param x0 - number.
+ * @returns region.
  */
 function autoPhaseRegion(
   re: DoubleArray,
@@ -210,9 +210,9 @@ function autoPhaseRegion(
 }
 
 /**
- * Holoborodko.
- * @param s - Array of float.
- * @returns Array of float.
+ * Applies the Holoborodko smoothing derivative filter.
+ * @param s - array of float.
+ * @returns array of float.
  */
 function holoborodko(s: DoubleArray): Float64Array<ArrayBuffer> {
   const dk = new Float64Array(s.length);
@@ -236,12 +236,12 @@ function holoborodko(s: DoubleArray): Float64Array<ArrayBuffer> {
 }
 
 /**
- * RobustBaseLineRegionsDetection.
- * @param s
- * @param options
- * @param options.magnitudeMode
- * @param options.maxDistanceToJoin
- * @param options.factorNoise
+ * Detects baseline regions using robust iterative noise estimation.
+ * @param s - input signal array.
+ * @param options - detection options.
+ * @param options.magnitudeMode - whether to use magnitude mode.
+ * @param options.maxDistanceToJoin - max distance to join nearby regions.
+ * @param options.factorNoise - noise factor for cutoff.
  */
 function robustBaseLineRegionsDetection(
   s: DoubleArray,
@@ -292,10 +292,10 @@ function robustBaseLineRegionsDetection(
 }
 
 /**
- * WeightedLinearRegression.
- * @param x
- * @param y
- * @param w
+ * Computes a weighted linear regression and returns [slope, intercept].
+ * @param x - x values.
+ * @param y - y values.
+ * @param w - weights.
  */
 function weightedLinearRegression(
   x: DoubleArray,

src/reim/reimFFT.ts

@@ -15,8 +15,8 @@ export interface ReimFFTOptions {
 }
 
 /**
- * ReimFFT.
- * @param data - complex spectrum
+ * Computes the FFT of a complex spectrum.
+ * @param data - complex spectrum.
  * @param options - options.
  * @returns FFT of complex spectrum.
  */

src/reim/reimPhaseCorrection.ts

@@ -16,10 +16,10 @@ export interface ReimPhaseCorrectionOptions {
 /**
  * Phase correction filter.
  * @param data - complex spectrum
- * @param phi0 - Angle in radians for zero order phase correction
- * @param phi1 - Angle in radians for first order phase correction
- * @param options
- * @returns - returns a new object {re:[], im:[]} unless inPlace=true
+ * @param phi0 - angle in radians for zero order phase correction.
+ * @param phi1 - angle in radians for first order phase correction.
+ * @param options - options.
+ * @returns a new object {re:[], im:[]} unless inPlace=true.
  */
 export function reimPhaseCorrection(
   data: DataReIm,

src/reim/reimZeroFilling.ts

@@ -8,7 +8,7 @@ import { createDoubleArray } from '../utils/createArray.ts';
  * This function make a zero filling to re and im part.
  * @param data - object of kind {re:[], im:[]}
  * @param totalLength - final number of points
- * @returns - New DataReIm object with zero-filled,
+ * @returns new DataReIm object with zero-filled,
  * truncated arrays if totalLength is smaller current length or
  * the same input if totalLength is equal that current length
  */

src/reimMatrix/reimMatrixPhaseCorrection.ts

@@ -14,10 +14,10 @@ export interface ReimMatrixPhaseCorrectionOptions {
  * Apply phase correction to a complex matrix along rows or columns.
  * All rows must have the same length.
  * @param data - complex matrix with re and im arrays of Float64Array rows
- * @param phi0 - Angle in radians for zero order phase correction
- * @param phi1 - Angle in radians for first order phase correction
- * @param options - options including direction ('rows' or 'columns', default 'rows')
- * @returns - complex matrix with corrected rows or columns
+ * @param phi0 - angle in radians for zero order phase correction.
+ * @param phi1 - angle in radians for first order phase correction.
+ * @param options - options including direction ('rows' or 'columns', default 'rows').
+ * @returns complex matrix with corrected rows or columns.
  */
 export function reimMatrixPhaseCorrection(
   data: DataReImMatrix,

src/utils/addWeights.ts

@@ -4,10 +4,10 @@ import type { NumberArray } from 'cheminfo-types';
  * add the provided weights to a particular given system matrix (lD'D) in the triplet form and y data. This function is not general
  * it assumes that diagonal coefficients are in the even indexes, it is the case of the matrix generated by createSystemMatrix function.
  * It simulates the matrix operation W + lD'D and Wy.
- * @param leftHandSide - The original system matrix to be updated, a lower triangular non-zeros of the system matrix (lambda D'D).
- * @param rightHandSide - The original vector to be updated.
- * @param weights - The weights to apply to the system matrix and vector.
- * @returns An object that contains the news left and right hand-side of the system.
+ * @param leftHandSide - the original system matrix to be updated, a lower triangular non-zeros of the system matrix (lambda D'D).
+ * @param rightHandSide - the original vector to be updated.
+ * @param weights - the weights to apply to the system matrix and vector.
+ * @returns an object that contains the new left and right hand-side of the system.
  */
 export function addWeights(
   leftHandSide: number[][],

src/utils/calculateAdaptiveWeights.ts

@@ -38,10 +38,10 @@ export interface CalculateAdaptiveWeightsOptions extends WeightsAndControlPoints
  * MAD (Median Absolute Deviation) is more robust to outliers and
  * the factor (1.4826) makes MAD scaled to be equivalent to the standard deviation for
  * normal distributions. {@link https://en.m.wikipedia.org/wiki/Median_absolute_deviation}.
- * @param yData - The original data.
- * @param baseline - The new baseline calculated.
- * @param weights - The current weights to be updated.
- * @param options - Options for updating weights.
+ * @param yData - the original data.
+ * @param baseline - the new baseline calculated.
+ * @param weights - the current weights to be updated.
+ * @param options - options for updating weights.
  * @returns new array of weights.
  */
 

src/utils/createFromToArray.ts

@@ -38,8 +38,8 @@ export interface CreateFromToArrayOptions {
 
 /**
  * Create an array with numbers between "from" and "to" of length "length"
- * @param options - options
- * @returns - array of distributed numbers between "from" and "to"
+ * @param options - options.
+ * @returns array of distributed numbers between "from" and "to".
  */
 export function createFromToArray(
   options: CreateFromToArrayOptions = {},

src/utils/createRandomArray.ts

@@ -41,8 +41,8 @@ export interface CreateRandomArrayOptions {
 
 /**
  * Create a random array of numbers of a specific length.
- * @param options
- * @returns - array of random floats normally distributed
+ * @param options - options.
+ * @returns array of random floats normally distributed.
  */
 export function createRandomArray(
   options: CreateRandomArrayOptions = {},

src/utils/createStepArray.ts

@@ -20,8 +20,8 @@ export interface CreateStepArrayOptions {
 
 /**
  * Create an array with numbers starting from "from" with step "step" of length "length".
- * @param options - options
- * @returns - array of distributed numbers with step "step" from "from"
+ * @param options - options.
+ * @returns array of distributed numbers with step "step" from "from".
  */
 export function createStepArray(
   options: CreateStepArrayOptions = {},

src/utils/createSystemMatrix.ts

@@ -8,9 +8,9 @@ export interface SystemMatrix {
  * Generates a lower triangular non-zeros of the first order smoother matrix (lambda D'D) where D is the derivate of the identity matrix
  * this function in combination with addWeights function can obtain (Q = W + lambda D'D) a penalized least square of Whittaker smoother,
  * it also generates a permutation encoded array.
- * @param dimension - The number of points in the matrix.
- * @param lambda - The factor of smoothness .
- * @returns An object containing the lower triangular non-zero elements of the matrix
+ * @param dimension - the number of points in the matrix.
+ * @param lambda - the factor of smoothness.
+ * @returns an object containing the lower triangular non-zero elements of the matrix
  * and the permutation encoded array.
  * @property lowerTriangularNonZeros - The lower triangular non-zero elements of the matrix in triplet form.
  * @property permutationEncodedArray - The permutation encoded array generated using the Cuthill-McKee algorithm.

src/utils/getCombinations.ts

@@ -1,8 +1,8 @@
 /**
  * Generate all combinations of choosing k items from n items.
- * @param n - Total number of items.
- * @param k - Number of items to choose.
- * @returns Array of combinations, where each combination is an array of indices.
+ * @param n - total number of items.
+ * @param k - number of items to choose.
+ * @returns array of combinations, where each combination is an array of indices.
  */
 export function getCombinations(n: number, k: number): number[][] {
   if (k === 0) return [[]];

src/utils/getCombinationsIterator.ts

@@ -1,8 +1,8 @@
 /**
  * Generate all combinations of choosing k items from n items as an iterator.
  * Useful for large combination sets to avoid storing all combinations in memory.
- * @param n - Total number of items.
- * @param k - Number of items to choose.
+ * @param n - total number of items.
+ * @param k - number of items to choose.
  * @yields Each combination as an array of indices.
  */