docs: improve JSDoc across 10 files (#373)

- Add missing JSDoc to zeroShift, matrixAutoCorrelation, matrixBoxPlot
- Document sorted-rows invariant on matrixBoxPlot
- Add interface property docs to MatrixBoxPlot
- Trim verbose xyEquallySpaced prose; fix stub from/to/variant descriptions
- Fix xGetFromToIndex descriptions that wrongly cited xyIntegration; add @default for from/to
- Fix truncated centerX description in xHistogram; add @default for logBaseX/logBaseY/absolute
- Add algorithm property JSDoc and fix stray character in xPadding
- Add zones property JSDoc to XYExtractOptions
- Fix mangled magnitudeMode description in reimAutoPhaseCorrection; add @returns
- Fix copy-pasted wrong descriptions on nbRows/nbColumns in matrixCreateEmpty

Author: lpatiny

src/matrix/matrixAutoCorrelation.ts

@@ -2,6 +2,12 @@ import type { DoubleMatrix } from 'cheminfo-types';
 
 import { xCorrelation } from '../x/index.ts';
 
+/**
+ * Correlates every column of a matrix against a single reference column.
+ * @param matrix - 2D matrix with at least 2 rows
+ * @param index - column index used as the reference signal. Defaults to `0`.
+ * @returns array of Pearson correlations, one value per column
+ */
 export function matrixAutoCorrelation(
   matrix: DoubleMatrix,
   index = 0,

src/matrix/matrixBoxPlot.ts

@@ -1,13 +1,25 @@
 import type { DoubleArray, DoubleMatrix } from 'cheminfo-types';
 
 export interface MatrixBoxPlot {
+  /** First quartile for each column. */
   q1: Float64Array;
+  /** Median for each column. */
   median: Float64Array;
+  /** Third quartile for each column. */
   q3: Float64Array;
+  /** Minimum value for each column (taken from the first row of the sorted matrix). */
   min: Float64Array;
+  /** Maximum value for each column (taken from the last row of the sorted matrix). */
   max: Float64Array;
 }
 
+/**
+ * Computes per-column box-plot statistics (min, Q1, median, Q3, max) for a matrix.
+ * The matrix rows must be sorted in ascending order — results will be wrong otherwise.
+ * Requires at least 5 rows.
+ * @param matrix - 2D matrix whose rows are sorted in ascending order
+ * @returns per-column box-plot statistics
+ */
 export function matrixBoxPlot(matrix: DoubleMatrix): MatrixBoxPlot {
   const nbRows = matrix.length;
   const nbColumns = matrix[0].length;

src/matrix/matrixCreateEmpty.ts

@@ -10,18 +10,18 @@ export interface MatrixCreateEmptyOptions<
   ArrayConstructorType extends NumberArrayConstructor = Float64ArrayConstructor,
 > {
   /**
-   * Matrix from which to extract nbRows and nbColumns
+   * Reference matrix used to derive default row and column counts.
    */
   matrix?: DoubleMatrix;
 
   /**
-   * Matrix from which to extract nbRows and nbColumns
+   * Number of rows in the new matrix.
    * @default matrix.length || 1
    */
   nbRows?: number;
 
   /**
-   * Matrix from which to extract nbRows and nbColumns
+   * Number of columns in the new matrix.
    * @default matrix[0].length || 1
    */
   nbColumns?: number;

src/reim/reimAutoPhaseCorrection.ts

@@ -8,7 +8,7 @@ import { reimPhaseCorrection } from './reimPhaseCorrection.ts';
 
 export interface AutoPhaseCorrectionOptions {
   /**
-   * if true it uses magnitude spectrum.boolean
+   * If true, uses the magnitude spectrum to detect baseline regions.
    * @default true
    */
   magnitudeMode?: boolean;
@@ -48,6 +48,7 @@ export interface AutoPhaseCorrectionOptions {
  * correction algorithm for high-resolution NMR data. 10.1002/mrc.4586
  * @param data - complex spectrum
  * @param options - options
+ * @returns phased spectrum together with the zero- and first-order correction angles (ph0, ph1) in degrees
  */
 
 export function reimAutoPhaseCorrection(

src/reim/zeroShift.ts

@@ -1,5 +1,12 @@
 import { xRotate } from '../x/index.ts';
 
+/**
+ * Circular shift that moves the zero-frequency component to the center of the array (FFT shift).
+ * For the inverse, the shift is reversed to restore the original layout.
+ * @param data - input array
+ * @param inverse - if true, shifts by ceil(n/2) instead of floor(n/2) to undo a previous zeroShift
+ * @returns shifted array
+ */
 export function zeroShift(
   data: Float64Array,
   inverse?: boolean,

src/x/xGetFromToIndex.ts

@@ -4,24 +4,26 @@ import { xFindClosestIndex } from './xFindClosestIndex.ts';
 
 export interface XGetFromToIndexOptions {
   /**
-   * First point for xyIntegration
+   * Start index (0-based, clamped to array bounds). Takes precedence over `from`.
    * @default 0
    */
   fromIndex?: number;
 
   /**
-   * Last point for xyIntegration
+   * End index (0-based, clamped to array bounds). Takes precedence over `to`.
    * @default x.length-1
    */
   toIndex?: number;
 
   /**
-   * First value for xyIntegration in the X scale
+   * Start value in the x scale; resolved to the nearest index.
+   * @default x[0]
    */
   from?: number;
 
   /**
-   * Last value for xyIntegration in the X scale
+   * End value in the x scale; resolved to the nearest index.
+   * @default x[x.length-1]
    */
   to?: number;
 }

src/x/xHistogram.ts

@@ -9,7 +9,7 @@ import { xMinValue } from './xMinValue.ts';
 
 export interface XHistogramOptions {
   /**
-   * Center the X value. We will enlarge the first and
+   * Center each slot's x value at the mid-point of the bin rather than at the left edge.
    * @default true
    */
   centerX?: boolean;
@@ -27,17 +27,20 @@ export interface XHistogramOptions {
   nbSlots?: number;
 
   /**
-   * We can first apply a log on x axis
+   * Apply log base transformation to input x values before binning.
+   * @default undefined
    */
   logBaseX?: number;
 
   /**
-   * We can apply a log on the resulting histogram
+   * Apply log base transformation to the resulting histogram y counts.
+   * @default undefined
    */
   logBaseY?: number;
 
   /**
-   * Take the absolute value
+   * Take the absolute value of each input element before binning.
+   * @default false
    */
   absolute?: boolean;
 

src/x/xPadding.ts

@@ -15,14 +15,18 @@ export interface XPaddingOptions {
    * @default 0
    */
   value?: number;
+  /**
+   * Padding strategy: `value` fills with a constant, `duplicate` repeats the first/last element, `circular` wraps the array.
+   * @default undefined
+   */
   algorithm?: 'value' | 'duplicate' | 'circular';
 }
 
 /**
- * This function pads an array
- *s
+ * Pads an array symmetrically on both sides.
  * @param array - the array that will be padded
  * @param options - options
+ * @returns padded Float64Array
  */
 export function xPadding(
   array: NumberArray,

src/xy/xyEquallySpaced.ts

@@ -9,19 +9,19 @@ import { xyCheck } from './xyCheck.ts';
 
 export interface XYEquallySpacedOptions {
   /**
-   * from
+   * Start of the output x range.
    * @default x[0]
    */
   from?: number;
 
   /**
-   * to
+   * End of the output x range.
    * @default x[x.length-1]
    */
   to?: number;
 
   /**
-   * variant
+   * `slot` averages y values within each bin; `smooth` uses the trapezoidal integral divided by the step size.
    * @default 'smooth'
    */
   variant?: 'slot' | 'smooth';
@@ -46,25 +46,11 @@ export interface XYEquallySpacedOptions {
 }
 
 /**
- * Function that returns a Number array of equally spaced numberOfPoints
- * containing a representation of intensities of the spectra arguments x
- * and y.
- *
- * The options parameter contains an object in the following form:
- * from: starting point
- * to: last point
- * numberOfPoints: number of points between from and to
- * variant: "slot" or "smooth" - smooth is the default option
- *
- * The slot variant consist that each point in an array is calculated
- * averaging the existing points between the slot that belongs to the current
- * value. The smooth variant is the same but takes the integral of the range
- * of the slot and divide by the step size between two points in an array.
- *
- * If exclusions zone are present, zones are ignored !
- * @param data - object containing 2 properties x and y
+ * Resample a spectrum to equally spaced x points.
+ * When `exclusions` are provided they take precedence and `zones` is ignored.
+ * @param data - object containing x and y arrays
  * @param options - options
- * @returns new object with x / y array with the equally spaced data.
+ * @returns resampled spectrum with equally spaced x values
  */
 
 export function xyEquallySpaced(

src/xy/xyExtract.ts

@@ -5,6 +5,10 @@ import { zonesNormalize } from '../zones/index.ts';
 import { xyCheck } from './xyCheck.ts';
 
 export interface XYExtractOptions {
+  /**
+   * Ranges to keep; points outside all zones are discarded.
+   * @default []
+   */
   zones?: FromTo[];
 }