docs: Imrprove generated docs

package.json

@@ -39,7 +39,7 @@
     "lint-eslint": "eslint './**/*.{ts, js, jcjs}'",
     "build": "vite build && pnpm run docs",
     "build-watch": "vite build --watch",
-    "docs": "npx typedoc src/index.ts",
+    "docs": "typedoc",
     "docs-open": "open ./docs/index.html",
     "release-preview": "semantic-release --no-ci --dry-run --debug",
     "link": "pnpm link --global",

src/index.ts

@@ -25,6 +25,11 @@ import {
   validateGetSurfacePointArguments,
 } from './utils/validation'
 
+/**
+ * @groupDescription API
+ * The API of the package
+ */
+
 // -----------------------------------------------------------------------------
 // Const
 // -----------------------------------------------------------------------------
@@ -59,17 +64,17 @@ export { interpolatePointOnCurveLinear } from './interpolate/pointOnCurve/linear
  * Computes a point on a surface defined by bounding curves at parameters u and
  * v.
  *
- * @param {Object} boundingCurves - An object containing curves that define the
- * surface boundaries.
- * @param {number} u - The parameter along the first dimension (typically
- * between 0 and 1).
- * @param {number} v - The parameter along the second dimension (typically
- * between 0 and 1).
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
+ * @param {number} u - The parameter along the first dimension (0–1).
+ * @param {number} v - The parameter along the second dimension (0–1).
+ * @param {Object} [config] - Configuration object.
  * @param {Function}
- * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to
- * interpolate points on the curves.
- * @returns {Object} The interpolated point on the surface.
+ * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function
+ * to interpolate points on the curves.
+ * @returns {Point} The interpolated point on the surface.
  * @throws {Error} If the arguments are invalid.
+ * @group API
  */
 export const getSurfacePoint = (
   boundingCurves: BoundingCurves,
@@ -97,19 +102,22 @@ export const getSurfacePoint = (
  * Generates intersection points on the surface based on the provided bounding
  * curves, columns, and rows.
  *
- * @param {Object} boundingCurves - An object containing curves that define the
- * surface boundaries.
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
  * @param {number | Array<number> | Array<Object>} columns - Either a number, an
  * array of numbers, or an array of column definitions, each containing a value
  * and an optional isGutter flag.
  * @param {number | Array<number> | Array<Object>} rows - Either a number, an
- * array of numbers, or an array of row definitions.
+ * array of numbers, or an array of row definitions, each containing a value and
+ * an optional isGutter flag.
+ * @param {Object} [config] - Configuration object.
  * @param {Function}
- * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to
- * interpolate points on the curves.
- * @returns {Array<Object>} An array of points representing the intersections on
- * the surface.
+ * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function
+ * to interpolate points on the curves.
+ * @returns {Points} An array of points representing the intersections on the
+ * surface.
  * @throws {Error} If the arguments are invalid.
+ * @group API
  */
 export const getSurfaceIntersectionPoints = (
   boundingCurves: BoundingCurves,
@@ -168,22 +176,24 @@ export const getSurfaceIntersectionPoints = (
  * Generates surface curves along the U-axis based on the provided bounding
  * curves, columns, and rows.
  *
- * @param {Object} boundingCurves - An object containing curves that define the
- * surface boundaries.
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
  * @param {number | Array<number> | Array<Object>} columns - Either a number, an
  * array of numbers, or an array of column definitions, each containing a value
  * and an optional isGutter flag.
  * @param {number | Array<number> | Array<Object>} rows - Either a number, an
- * array of numbers, or an array of row definitions, each containing a value
- * and an optional isGutter flag.
+ * array of numbers, or an array of row definitions, each containing a value and
+ * an optional isGutter flag.
+ * @param {Object} [config] - Configuration object.
  * @param {Function}
- * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to
- * interpolate points on the curves.
- * @param {Function} [interpolateLineU=interpolateStraightLineU] - A
+ * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function
+ * to interpolate points on the curves.
+ * @param {Function} [config.interpolateLineU=interpolateStraightLineU] - A
  * function to interpolate lines along the U-axis.
- * @returns {Array<Array<Object>>} A 2D array of curves representing the surface
- * along the U-axis.
+ * @returns {StepCurves[]} A 2D array of curves representing the surface along
+ * the U-axis.
  * @throws {Error} If the arguments are invalid.
+ * @group API
  */
 export const getSurfaceCurvesU = (
   boundingCurves: BoundingCurves,
@@ -259,22 +269,24 @@ export const getSurfaceCurvesU = (
  * Generates surface curves along the V-axis based on the provided bounding
  * curves, columns, and rows.
  *
- * @param {Object} boundingCurves - An object containing curves that define the
- * surface boundaries.
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
  * @param {number | Array<number> | Array<Object>} columns - Either a number, an
  * array of numbers, or an array of column definitions, each containing a value
  * and an optional isGutter flag.
  * @param {number | Array<number> | Array<Object>} rows - Either a number, an
- * array of numbers, or an array of row definitions, each containing a value
- * and an optional isGutter flag.
+ * array of numbers, or an array of row definitions, each containing a value and
+ * an optional isGutter flag.
+ * @param {Object} [config] - Configuration object.
  * @param {Function}
- * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to
- * interpolate points on the curves.
- * @param {Function} [interpolateLineV=interpolateStraightLineV] - A
+ * [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function
+ * to interpolate points on the curves.
+ * @param {Function} [config.interpolateLineV=interpolateStraightLineV] - A
  * function to interpolate lines along the V-axis.
  * @returns {Array<Array<Object>>} A 2D array of curves representing the surface
  * along the V-axis.
  * @throws {Error} If the arguments are invalid.
+ * @group API
  */
 export const getSurfaceCurvesV = (
   boundingCurves: BoundingCurves,
@@ -351,23 +363,25 @@ export const getSurfaceCurvesV = (
  * Generates surface curves along both the U-axis and V-axis based on the
  * provided bounding curves, columns, and rows.
  *
- * @param {Object} boundingCurves - An object containing curves that define the
+ * @param {BoundingCurves} boundingCurves - An object containing curves that define the
  * surface boundaries.
  * @param {number | Array<number> | Array<Object>} columns - Either a number, an
  * array of numbers, or an array of column definitions, each containing a value
  * and an optional isGutter flag.
  * @param {number | Array<number> | Array<Object>} rows - Either a number, an
- * array of numbers, or an array of row definitions.
- * @param {Function}
- * [interpolatePointOnCurve=interpolatePointOnCurveEvenlySpaced] - A function to
+ * array of numbers, or an array of row definitions, each containing a value
+ * and an optional isGutter flag.
+ * @param {Object} [config] - Configuration object.
+ * @param {Function} [config.interpolatePointOnCurve=interpolatePointOnCurveDefault] - A function to
  * interpolate points on the curves.
- * @param {Function} [interpolateLineU=interpolateStraightLineU] - A
+ * @param {Function} [config.interpolateLineU=interpolateStraightLineU] - A
  * function to interpolate lines along the U-axis.
- * @param {Function} [interpolateLineV=interpolateStraightLineV] - A
+ * @param {Function} [config.interpolateLineV=interpolateStraightLineV] - A
  * function to interpolate lines along the V-axis.
- * @returns {Object} An object containing 2D arrays of curves representing the
+ * @returns {UVCurves} An object containing 2D arrays of curves representing the
  * surface along both the U-axis and V-axis.
  * @throws {Error} If the arguments are invalid.
+ * @group API
  */
 export const getSurfaceCurves = (
   boundingCurves: BoundingCurves,

src/interpolate/curves/curved.ts

@@ -10,6 +10,24 @@ import { interpolateStraightLineU, interpolateStraightLineV } from './straight'
 const T_MIDPOINT_1 = 0.25
 const T_MIDPOINT_2 = 0.75
 
+// -----------------------------------------------------------------------------
+// Exports
+// -----------------------------------------------------------------------------
+
+/**
+ * Interpolates a cubic Bezier curve along the U direction of a surface defined
+ * by bounding curves.
+ *
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
+ * @param {number} vStart - The starting parameter along the V direction.
+ * @param {number} vSize - The size of the step along the V direction.
+ * @param {number} vEnd - The ending parameter along the V direction.
+ * @param {number} uStart - The starting parameter along the U direction.
+ * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to
+ * interpolate points on the curves.
+ * @returns {Curve} The interpolated cubic Bezier curve.
+ */
 export const interpolateCurveU = (
   boundingCurves: BoundingCurves,
   vStart: number,
@@ -49,6 +67,20 @@ export const interpolateCurveU = (
   return curve
 }
 
+/**
+ * Interpolates a cubic Bezier curve along the V direction of a surface defined
+ * by bounding curves.
+ *
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
+ * @param {number} uStart - The starting parameter along the U direction.
+ * @param {number} uSize - The size of the step along the U direction.
+ * @param {number} uEnd - The ending parameter along the U direction.
+ * @param {number} vStart - The starting parameter along the V direction.
+ * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to
+ * interpolate points on the curves.
+ * @returns {Curve} The interpolated cubic Bezier curve.
+ */
 export const interpolateCurveV = (
   boundingCurves: BoundingCurves,
   uStart: number,

src/interpolate/curves/straight.ts

@@ -5,6 +5,19 @@ import { interpolatePointOnSurface } from '../pointOnSurface/bilinear'
 // Exports
 // -----------------------------------------------------------------------------
 
+/**
+ * Interpolates a straight line along the U direction of a surface defined
+ * by bounding curves.
+ *
+ * @param {BoundingCurves} boundingCurves - An object containing curves that define the
+ * surface boundaries.
+ * @param {number} uStart - The starting parameter along the U direction.
+ * @param {number} uSize - The size of the step along the U direction.
+ * @param {number} uEnd - The ending parameter along the U direction.
+ * @param {number} vStart - The starting parameter along the V direction.
+ * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to interpolate points on the curves.
+ * @returns {Curve} The interpolated straight line as a cubic Bezier curve.
+ */
 export const interpolateStraightLineU = (
   boundingCurves: BoundingCurves,
   uStart: number,
@@ -36,6 +49,20 @@ export const interpolateStraightLineU = (
   }
 }
 
+/**
+ * Interpolates a straight line along the V direction of a surface defined by
+ * bounding curves.
+ *
+ * @param {BoundingCurves} boundingCurves - An object containing curves that
+ * define the surface boundaries.
+ * @param {number} uStart - The starting parameter along the U direction.
+ * @param {number} uSize - The size of the step along the U direction.
+ * @param {number} uEnd - The ending parameter along the U direction.
+ * @param {number} vStart - The starting parameter along the V direction.
+ * @param {InterpolatePointOnCurve} interpolatePointOnCurve - A function to
+ * interpolate points on the curves.
+ * @returns {Curve} The interpolated straight line as a cubic Bezier curve.
+ */
 export const interpolateStraightLineV = (
   boundingCurves: BoundingCurves,
   uStart: number,

src/interpolate/pointOnCurve/even.ts

@@ -61,6 +61,16 @@ const getLutForCurve = memoize((curve, precision) => {
 // Exports
 // -----------------------------------------------------------------------------
 
+/**
+ * Interpolates a point on a curve such that the points are evenly spaced.
+ *
+ * @param {Object} options - Configuration options.
+ * @param {number} options.precision - The number of points used to approximate
+ * the curve. Increasing this number improves accuracy at the cost of
+ * performance.
+ * @returns {Function} A function that takes a parameter `t` and a `curve`, and
+ * returns an interpolated point on the curve.
+ */
 export const interpolatePointOnCurveEvenlySpaced =
   (
     // Get an approximation using an arbitrary number of points. Increase for

src/interpolate/pointOnCurve/linear.ts

@@ -37,6 +37,14 @@ const interpolate = (
 // Exports
 // -----------------------------------------------------------------------------
 
+/**
+ * Interpolates a point on a curve using linear interpolation. Note that this
+ * will not result in the points being evenly spaced.
+ *
+ * @param {number} t - The parameter along the curve, typically between 0 and 1.
+ * @param {Curve} curve - The curve on which to interpolate the point.
+ * @returns {Point} The interpolated point on the curve.
+ */
 export const interpolatePointOnCurveLinear = (
   t: number,
   curve: Curve

tests/snapshotData.js

@@ -6,6 +6,7 @@ import {
   getSurfaceIntersectionPoints,
   getSurfacePoint,
 } from '../src/index.js'
+
 import fixtures from './fixtures.js'
 import { __dirname, writeFileAsync } from './helpers.js'
 

typedoc.cjs

@@ -0,0 +1,8 @@
+/** @type {import('typedoc').TypeDocOptions} */
+module.exports = {
+  entryPoints: ['./src/index.ts'],
+  out: 'docs',
+  categorizeByGroup: true,
+  groupOrder: ['API', '*'],
+  sort: 'source-order',
+}