Docs: More JSDoc. (#30642)

examples/jsm/curves/CurveExtras.js

@@ -13,10 +13,20 @@ import {
  * https://prideout.net/blog/old/blog/index.html@p=44.html
  */
 
-// GrannyKnot
-
+/**
+ * A Granny Knot curve.
+ *
+ * @augments Curve
+ */
 class GrannyKnot extends Curve {
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -33,18 +43,39 @@ class GrannyKnot extends Curve {
 
 }
 
-// HeartCurve
-
+/**
+ * A heart curve.
+ *
+ * @augments Curve
+ */
 class HeartCurve extends Curve {
 
+	/**
+	 * Constructs a new heart curve.
+	 *
+	 * @param {number} [scale=5] - The curve's scale.
+	 */
 	constructor( scale = 5 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 5
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -61,18 +92,39 @@ class HeartCurve extends Curve {
 
 }
 
-// Viviani's Curve
-
+/**
+ * A Viviani curve.
+ *
+ * @augments Curve
+ */
 class VivianiCurve extends Curve {
 
+	/**
+	 * Constructs a new Viviani curve.
+	 *
+	 * @param {number} [scale=70] - The curve's scale.
+	 */
 	constructor( scale = 70 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 70
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -90,10 +142,20 @@ class VivianiCurve extends Curve {
 
 }
 
-// KnotCurve
-
+/**
+ * A knot curve.
+ *
+ * @augments Curve
+ */
 class KnotCurve extends Curve {
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -113,11 +175,20 @@ class KnotCurve extends Curve {
 
 }
 
-
-// HelixCurve
-
+/**
+ * A helix curve.
+ *
+ * @augments Curve
+ */
 class HelixCurve extends Curve {
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -137,18 +208,39 @@ class HelixCurve extends Curve {
 
 }
 
-// TrefoilKnot
-
+/**
+ * A Trefoil Knot.
+ *
+ * @augments Curve
+ */
 class TrefoilKnot extends Curve {
 
+	/**
+	 * Constructs a new Trefoil Knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -165,18 +257,39 @@ class TrefoilKnot extends Curve {
 
 }
 
-// TorusKnot
-
+/**
+ * A torus knot.
+ *
+ * @augments Curve
+ */
 class TorusKnot extends Curve {
 
+	/**
+	 * Constructs a new torus knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -196,18 +309,39 @@ class TorusKnot extends Curve {
 
 }
 
-// CinquefoilKnot
-
+/**
+ * A Cinquefoil Knot.
+ *
+ * @augments Curve
+ */
 class CinquefoilKnot extends Curve {
 
+	/**
+	 * Constructs a new Cinquefoil Knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -227,19 +361,39 @@ class CinquefoilKnot extends Curve {
 
 }
 
-
-// TrefoilPolynomialKnot
-
+/**
+ * A Trefoil Polynomial Knot.
+ *
+ * @augments Curve
+ */
 class TrefoilPolynomialKnot extends Curve {
 
+	/**
+	 * Constructs a new Trefoil Polynomial Knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -263,18 +417,39 @@ function scaleTo( x, y, t ) {
 
 }
 
-// FigureEightPolynomialKnot
-
+/**
+ * A Figure Eight Polynomial Knot.
+ *
+ * @augments Curve
+ */
 class FigureEightPolynomialKnot extends Curve {
 
+	/**
+	 * Constructs a new Figure Eight Polynomial Knot.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 1 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -291,18 +466,39 @@ class FigureEightPolynomialKnot extends Curve {
 
 }
 
-// DecoratedTorusKnot4a
-
+/**
+ * A Decorated Torus Knot 4a.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot4a extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 4a.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -319,18 +515,39 @@ class DecoratedTorusKnot4a extends Curve {
 
 }
 
-// DecoratedTorusKnot4b
-
+/**
+ * A Decorated Torus Knot 4b.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot4b extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 4b.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -347,19 +564,39 @@ class DecoratedTorusKnot4b extends Curve {
 
 }
 
-
-// DecoratedTorusKnot5a
-
+/**
+ * A Decorated Torus Knot 5a.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot5a extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 5a.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -376,18 +613,39 @@ class DecoratedTorusKnot5a extends Curve {
 
 }
 
-// DecoratedTorusKnot5c
-
+/**
+ * A Decorated Torus Knot 5c.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot5c extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 5c.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;

examples/jsm/curves/NURBSCurve.js

@@ -6,34 +6,63 @@ import {
 import * as NURBSUtils from '../curves/NURBSUtils.js';
 
 /**
- * NURBS curve object
+ * This class represents a NURBS curve.
  *
- * Derives from Curve, overriding getPoint and getTangent.
+ * Implementation is based on `(x, y [, z=0 [, w=1]])` control points with `w=weight`.
  *
- * Implementation is based on (x, y [, z=0 [, w=1]]) control points with w=weight.
- *
- **/
-
+ * @augments Curve
+ */
 class NURBSCurve extends Curve {
 
-	constructor(
-		degree,
-		knots /* array of reals */,
-		controlPoints /* array of Vector(2|3|4) */,
-		startKnot /* index in knots */,
-		endKnot /* index in knots */
-	) {
+	/**
+	 * Constructs a new NURBS curve.
+	 *
+	 * @param {number} degree - The NURBS degree.
+	 * @param {Array<number>} knots - The knots as a flat array of numbers.
+	 * @param {Array<Vector2|Vector3|Vector4>} controlPoints - An array holding control points.
+	 * @param {number} [startKnot] - Index of the start knot into the `knots` array.
+	 * @param {number} [endKnot] - Index of the end knot into the `knots` array.
+	 */
+	constructor( degree, knots, controlPoints, startKnot, endKnot ) {
 
 		super();
 
 		const knotsLength = knots ? knots.length - 1 : 0;
 		const pointsLength = controlPoints ? controlPoints.length : 0;
 
+		/**
+		 * The NURBS degree.
+		 *
+		 * @type {number}
+		 */
 		this.degree = degree;
+
+		/**
+		 * The knots as a flat array of numbers.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.knots = knots;
+
+		/**
+		 * An array of control points.
+		 *
+		 * @type {Array<Vector4>}
+		 */
 		this.controlPoints = [];
-		// Used by periodic NURBS to remove hidden spans
+
+		/**
+		 * Index of the start knot into the `knots` array.
+		 *
+		 * @type {number}
+		 */
 		this.startKnot = startKnot || 0;
+
+		/**
+		 * Index of the end knot into the `knots` array.
+		 *
+		 * @type {number}
+		 */
 		this.endKnot = endKnot || knotsLength;
 
 		for ( let i = 0; i < pointsLength; ++ i ) {
@@ -46,6 +75,13 @@ class NURBSCurve extends Curve {
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -66,6 +102,13 @@ class NURBSCurve extends Curve {
 
 	}
 
+	/**
+	 * Returns a unit vector tangent for the given interpolation factor.
+	 *
+	 * @param {number} t - The interpolation factor.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The tangent vector.
+	 */
 	getTangent( t, optionalTarget = new Vector3() ) {
 
 		const tangent = optionalTarget;

examples/jsm/curves/NURBSSurface.js

@@ -4,19 +4,56 @@ import {
 import * as NURBSUtils from '../curves/NURBSUtils.js';
 
 /**
- * NURBS surface object
+ * This class represents a NURBS surface.
  *
- * Implementation is based on (x, y [, z=0 [, w=1]]) control points with w=weight.
- **/
-
+ * Implementation is based on `(x, y [, z=0 [, w=1]])` control points with `w=weight`.
+ */
 class NURBSSurface {
 
-	constructor( degree1, degree2, knots1, knots2 /* arrays of reals */, controlPoints /* array^2 of Vector(2|3|4) */ ) {
-
+	/**
+	 * Constructs a new NURBS surface.
+	 *
+	 * @param {number} degree1 - The first NURBS degree.
+	 * @param {number} degree2 - The second NURBS degree.
+	 * @param {Array<number>} knots1 - The first knots as a flat array of numbers.
+	 * @param {Array<number>} knots2 - The second knots as a flat array of numbers.
+	 * @param {Array<Array<Vector2|Vector3|Vector4>>} controlPoints - An array^2 holding control points.
+	 */
+	constructor( degree1, degree2, knots1, knots2, controlPoints ) {
+
+		/**
+		 * The first NURBS degree.
+		 *
+		 * @type {number}
+		 */
 		this.degree1 = degree1;
+
+		/**
+		 * The second NURBS degree.
+		 *
+		 * @type {number}
+		 */
 		this.degree2 = degree2;
+
+		/**
+		 * The first knots as a flat array of numbers.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.knots1 = knots1;
+
+		/**
+		 * The second knots as a flat array of numbers.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.knots2 = knots2;
+
+		/**
+		 *  An array holding arrays of control points.
+		 *
+		 * @type {Array<Array<Vector2|Vector3|Vector4>>}
+		 */
 		this.controlPoints = [];
 
 		const len1 = knots1.length - degree1 - 1;
@@ -38,6 +75,13 @@ class NURBSSurface {
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor. This vector lies on the NURBS surface.
+	 *
+	 * @param {number} t1 - The first interpolation factor representing the `u` position on the surface. Must be in the range `[0,1]`.
+	 * @param {number} t2 - The second interpolation factor representing the `v` position on the surface. Must be in the range `[0,1]`.
+	 * @param {Vector3} target - The target vector the result is written to.
+	 */
 	getPoint( t1, t2, target ) {
 
 		const u = this.knots1[ 0 ] + t1 * ( this.knots1[ this.knots1.length - 1 ] - this.knots1[ 0 ] ); // linear mapping t1->u

examples/jsm/curves/NURBSUtils.js

@@ -3,26 +3,16 @@ import {
 	Vector4
 } from 'three';
 
+/** @module NURBSUtils */
+
 /**
- * NURBS utils
+ * Finds knot vector span.
  *
- * See NURBSCurve and NURBSSurface.
- **/
-
-
-/**************************************************************
- *	NURBS Utils
- **************************************************************/
-
-/*
-Finds knot vector span.
-
-p : degree
-u : parametric value
-U : knot vector
-
-returns the span
-*/
+ * @param {number} p - The degree.
+ * @param {number} u - The parametric value.
+ * @param {Array<number>} U - The knot vector.
+ * @return {number} The span.
+ */
 function findSpan( p, u, U ) {
 
 	const n = U.length - p - 1;
@@ -63,17 +53,15 @@ function findSpan( p, u, U ) {
 
 }
 
-
-/*
-Calculate basis functions. See The NURBS Book, page 70, algorithm A2.2
-
-span : span in which u lies
-u    : parametric point
-p    : degree
-U    : knot vector
-
-returns array[p+1] with basis functions values.
-*/
+/**
+ * Calculates basis functions. See The NURBS Book, page 70, algorithm A2.2.
+ *
+ * @param {number} span - The span in which `u` lies.
+ * @param {number} u - The parametric value.
+ * @param {number} p - The degree.
+ * @param {Array<number>} U - The knot vector.
+ * @return {Array<number>} Array[p+1] with basis functions values.
+ */
 function calcBasisFunctions( span, u, p, U ) {
 
 	const N = [];
@@ -106,17 +94,15 @@ function calcBasisFunctions( span, u, p, U ) {
 
 }
 
-
-/*
-Calculate B-Spline curve points. See The NURBS Book, page 82, algorithm A3.1.
-
-p : degree of B-Spline
-U : knot vector
-P : control points (x, y, z, w)
-u : parametric point
-
-returns point for given u
-*/
+/**
+ * Calculates B-Spline curve points. See The NURBS Book, page 82, algorithm A3.1.
+ *
+ * @param {number} p - The degree of the B-Spline.
+ * @param {Array<number>} U - The knot vector.
+ * @param {Array<Vector4>} P - The control points
+ * @param {number} u - The parametric point.
+ * @return {Vector4} The point for given `u`.
+ */
 function calcBSplinePoint( p, U, P, u ) {
 
 	const span = findSpan( p, u, U );
@@ -139,18 +125,16 @@ function calcBSplinePoint( p, U, P, u ) {
 
 }
 
-
-/*
-Calculate basis functions derivatives. See The NURBS Book, page 72, algorithm A2.3.
-
-span : span in which u lies
-u    : parametric point
-p    : degree
-n    : number of derivatives to calculate
-U    : knot vector
-
-returns array[n+1][p+1] with basis functions derivatives
-*/
+/**
+ * Calculates basis functions derivatives. See The NURBS Book, page 72, algorithm A2.3.
+ *
+ * @param {number} span - The span in which `u` lies.
+ * @param {number} u - The parametric point.
+ * @param {number} p - The degree.
+ * @param {number} n - number of derivatives to calculate
+ * @param {Array<number>} U - The knot vector.
+ * @return {Array<Array<number>>} An array[n+1][p+1] with basis functions derivatives.
+ */
 function calcBasisFunctionDerivatives( span, u, p, n, U ) {
 
 	const zeroArr = [];
@@ -273,18 +257,16 @@ function calcBasisFunctionDerivatives( span, u, p, n, U ) {
 
 }
 
-
-/*
-	Calculate derivatives of a B-Spline. See The NURBS Book, page 93, algorithm A3.2.
-
-	p  : degree
-	U  : knot vector
-	P  : control points
-	u  : Parametric points
-	nd : number of derivatives
-
-	returns array[d+1] with derivatives
-	*/
+/**
+ * Calculates derivatives of a B-Spline. See The NURBS Book, page 93, algorithm A3.2.
+ *
+ * @param {number} p - The degree.
+ * @param {Array<number>} U - The knot vector.
+ * @param {Array<Vector4>} P - The control points
+ * @param {number} u - The parametric point.
+ * @param {number} nd - The number of derivatives.
+ * @return {Array<Vector4>} An array[d+1] with derivatives.
+ */
 function calcBSplineDerivatives( p, U, P, u, nd ) {
 
 	const du = nd < p ? nd : p;
@@ -330,12 +312,13 @@ function calcBSplineDerivatives( p, U, P, u, nd ) {
 
 }
 
-
-/*
-Calculate "K over I"
-
-returns k!/(i!(k-i)!)
-*/
+/**
+ * Calculates "K over I".
+ *
+ * @param {number} k - The K value.
+ * @param {number} i - The I value.
+ * @return {number} k!/(i!(k-i)!)
+ */
 function calcKoverI( k, i ) {
 
 	let nom = 1;
@@ -364,14 +347,12 @@ function calcKoverI( k, i ) {
 
 }
 
-
-/*
-Calculate derivatives (0-nd) of rational curve. See The NURBS Book, page 127, algorithm A4.2.
-
-Pders : result of function calcBSplineDerivatives
-
-returns array with derivatives for rational curve.
-*/
+/**
+ * Calculates derivatives (0-nd) of rational curve. See The NURBS Book, page 127, algorithm A4.2.
+ *
+ * @param {Array<Vector4>} Pders - Array with derivatives.
+ * @return {Array<Vector4>} An array with derivatives for rational curve.
+ */
 function calcRationalCurveDerivatives( Pders ) {
 
 	const nd = Pders.length;
@@ -406,18 +387,16 @@ function calcRationalCurveDerivatives( Pders ) {
 
 }
 
-
-/*
-Calculate NURBS curve derivatives. See The NURBS Book, page 127, algorithm A4.2.
-
-p  : degree
-U  : knot vector
-P  : control points in homogeneous space
-u  : parametric points
-nd : number of derivatives
-
-returns array with derivatives.
-*/
+/**
+ * Calculates NURBS curve derivatives. See The NURBS Book, page 127, algorithm A4.2.
+ *
+ * @param {number} p - The degree.
+ * @param {Array<number>} U - The knot vector.
+ * @param {Array<Vector4>} P - The control points in homogeneous space.
+ * @param {number} u - The parametric point.
+ * @param {number} nd - The number of derivatives.
+ * @return {Array<Vector4>} array with derivatives for rational curve.
+ */
 function calcNURBSDerivatives( p, U, P, u, nd ) {
 
 	const Pders = calcBSplineDerivatives( p, U, P, u, nd );
@@ -425,17 +404,18 @@ function calcNURBSDerivatives( p, U, P, u, nd ) {
 
 }
 
-
-/*
-Calculate rational B-Spline surface point. See The NURBS Book, page 134, algorithm A4.3.
-
-p, q : degrees of B-Spline surface
-U, V : knot vectors
-P    : control points (x, y, z, w)
-u, v : parametric values
-
-returns point for given (u, v)
-*/
+/**
+ * Calculates a rational B-Spline surface point. See The NURBS Book, page 134, algorithm A4.3.
+ *
+ * @param {number} p - The first degree of B-Spline surface.
+ * @param {number} q - The second degree of B-Spline surface.
+ * @param {Array<number>} U - The first knot vector.
+ * @param {Array<number>} V - The second knot vector.
+ * @param {Array<Vector4>} P - The control points in homogeneous space.
+ * @param {number} u - The first parametric point.
+ * @param {number} v - The second parametric point.
+ * @param {Vector3} target - The target vector.
+ */
 function calcSurfacePoint( p, q, U, V, P, u, v, target ) {
 
 	const uspan = findSpan( p, u, U );
@@ -472,16 +452,21 @@ function calcSurfacePoint( p, q, U, V, P, u, v, target ) {
 
 }
 
-/*
-Calculate rational B-Spline volume point. See The NURBS Book, page 134, algorithm A4.3.
-
-p, q, r   : degrees of B-Splinevolume
-U, V, W   : knot vectors
-P         : control points (x, y, z, w)
-u, v, w   : parametric values
-
-returns point for given (u, v, w)
-*/
+/**
+ * Calculates a rational B-Spline volume point. See The NURBS Book, page 134, algorithm A4.3.
+ *
+ * @param {number} p - The first degree of B-Spline surface.
+ * @param {number} q - The second degree of B-Spline surface.
+ * @param {number} r - The third degree of B-Spline surface.
+ * @param {Array<number>} U - The first knot vector.
+ * @param {Array<number>} V - The second knot vector.
+ * @param {Array<number>} W - The third knot vector.
+ * @param {Array<Vector4>} P - The control points in homogeneous space.
+ * @param {number} u - The first parametric point.
+ * @param {number} v - The second parametric point.
+ * @param {number} w - The third parametric point.
+ * @param {Vector3} target - The target vector.
+ */
 function calcVolumePoint( p, q, r, U, V, W, P, u, v, w, target ) {
 
 	const uspan = findSpan( p, u, U );
@@ -530,7 +515,6 @@ function calcVolumePoint( p, q, r, U, V, W, P, u, v, w, target ) {
 
 }
 
-
 export {
 	findSpan,
 	calcBasisFunctions,

examples/jsm/curves/NURBSVolume.js

@@ -4,13 +4,23 @@ import {
 import * as NURBSUtils from '../curves/NURBSUtils.js';
 
 /**
- * NURBS volume object
+ * This class represents a NURBS volume.
  *
- * Implementation is based on (x, y, z [, w=1]]) control points with w=weight.
- **/
-
+ * Implementation is based on `(x, y [, z=0 [, w=1]])` control points with `w=weight`.
+ */
 class NURBSVolume {
 
+	/**
+	 * Constructs a new NURBS surface.
+	 *
+	 * @param {number} degree1 - The first NURBS degree.
+	 * @param {number} degree2 - The second NURBS degree.
+	 * @param {number} degree3 - The third NURBS degree.
+	 * @param {Array<number>} knots1 - The first knots as a flat array of numbers.
+	 * @param {Array<number>} knots2 - The second knots as a flat array of numbers.
+	 * @param {Array<number>} knots3 - The third knots as a flat array of numbers.
+	 * @param {Array<Array<Array<Vector2|Vector3|Vector4>>>} controlPoints - An array^3 holding control points.
+	 */
 	constructor( degree1, degree2, degree3, knots1, knots2, knots3 /* arrays of reals */, controlPoints /* array^3 of Vector(2|3|4) */ ) {
 
 		this.degree1 = degree1;
@@ -47,6 +57,14 @@ class NURBSVolume {
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor. This vector lies within the NURBS volume.
+	 *
+	 * @param {number} t1 - The first interpolation factor representing the `u` position within the volume. Must be in the range `[0,1]`.
+	 * @param {number} t2 - The second interpolation factor representing the `v` position within the volume. Must be in the range `[0,1]`.
+	 * @param {number} t3 - The third interpolation factor representing the `w` position within the volume. Must be in the range `[0,1]`.
+	 * @param {Vector3} target - The target vector the result is written to.
+	 */
 	getPoint( t1, t2, t3, target ) {
 
 		const u = this.knots1[ 0 ] + t1 * ( this.knots1[ this.knots1.length - 1 ] - this.knots1[ 0 ] ); // linear mapping t1->u

examples/jsm/environments/DebugEnvironment.js

@@ -8,8 +8,30 @@ import {
 	Scene,
 } from 'three';
 
+/**
+ * This class represents a scene with a very basic room setup that can be used as
+ * input for {@link PMREMGenerator#fromScene}. The resulting PMREM represents the room's
+ * lighting and can be used for Image Based Lighting by assigning it to {@link Scene#environment}
+ * or directly as an environment map to PBR materials.
+ *
+ * This class uses a simple room setup and should only be used for development purposes.
+ * A more appropriate setup for production is {@link RoomEnvironment}.
+ *
+ * ```js
+ * const environment = new DebugEnvironment();
+ * const pmremGenerator = new THREE.PMREMGenerator( renderer );
+ *
+ * const envMap = pmremGenerator.fromScene( environment ).texture;
+ * scene.environment = envMap;
+ * ```
+ *
+ * @augments Scene
+ */
 class DebugEnvironment extends Scene {
 
+	/**
+	 * Constructs a new debug environment.
+	 */
 	constructor() {
 
 		super();
@@ -47,6 +69,33 @@ class DebugEnvironment extends Scene {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the environment is no longer required.
+	 */
+	dispose() {
+
+		const resources = new Set();
+
+		this.traverse( ( object ) => {
+
+			if ( object.isMesh ) {
+
+				resources.add( object.geometry );
+				resources.add( object.material );
+
+			}
+
+		} );
+
+		for ( const resource of resources ) {
+
+			resource.dispose();
+
+		}
+
+	}
+
 }
 
 export { DebugEnvironment };

examples/jsm/environments/RoomEnvironment.js

@@ -12,6 +12,25 @@ import {
  	Scene,
 } from 'three';
 
+/**
+ * This class represents a scene with a basic room setup that can be used as
+ * input for {@link PMREMGenerator#fromScene}. The resulting PMREM represents the room's
+ * lighting and can be used for Image Based Lighting by assigning it to {@link Scene#environment}
+ * or directly as an environment map to PBR materials.
+ *
+ * The implementation is based on the [EnvironmentScene](https://github.com/google/model-viewer/blob/master/packages/model-viewer/src/three-components/EnvironmentScene.ts)
+ * component from the `model-viewer` project.
+ *
+ * ```js
+ * const environment = new RoomEnvironment();
+ * const pmremGenerator = new THREE.PMREMGenerator( renderer );
+ *
+ * const envMap = pmremGenerator.fromScene( environment ).texture;
+ * scene.environment = envMap;
+ * ```
+ *
+ * @augments Scene
+ */
 class RoomEnvironment extends Scene {
 
 	constructor() {
@@ -108,6 +127,10 @@ class RoomEnvironment extends Scene {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the environment is no longer required.
+	 */
 	dispose() {
 
 		const resources = new Set();

src/geometries/ExtrudeGeometry.js

@@ -1,25 +1,3 @@
-/**
- * Creates extruded geometry from a path shape.
- *
- * parameters = {
- *
- *  curveSegments: <int>, // number of points on the curves
- *  steps: <int>, // number of points for z-side extrusions / used for subdividing segments of extrude spline too
- *  depth: <float>, // Depth to extrude the shape
- *
- *  bevelEnabled: <bool>, // turn on bevel
- *  bevelThickness: <float>, // how deep into the original shape bevel goes
- *  bevelSize: <float>, // how far from shape outline (including bevelOffset) is bevel
- *  bevelOffset: <float>, // how far from shape outline does bevel start
- *  bevelSegments: <int>, // number of bevel layers
- *
- *  extrudePath: <THREE.Curve> // curve to extrude shape along
- *
- *  UVGenerator: <Object> // object that provides UV generator functions
- *
- * }
- */
-
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import * as Curves from '../extras/curves/Curves.js';
@@ -55,17 +33,7 @@ class ExtrudeGeometry extends BufferGeometry {
 	 * Constructs a new extrude geometry.
 	 *
 	 * @param {Shape|Array<Shape>} [shapes] - A shape or an array of shapes.
-	 * @param {Object} [options={}] - The extrude settings.
-	 * @param {number} [options.curveSegments=12] - Number of points on the curves.
-	 * @param {number} [options.steps=1] - Number of points used for subdividing segments along the depth of the extruded spline.
-	 * @param {number} [options.depth=1] - Depth to extrude the shape.
-	 * @param {boolean} [options.bevelEnabled=true] - Whether to beveling to the shape or not.
-	 * @param {number} [options.bevelThickness=0.2] - How deep into the original shape the bevel goes.
-	 * @param {number} [options.bevelSize=bevelThickness-0.1] - Distance from the shape outline that the bevel extends.
-	 * @param {number} [options.bevelOffset=0] - Distance from the shape outline that the bevel starts.
-	 * @param {number} [options.bevelSegments=3] - Number of bevel layers.
-	 * @param {?Curve} [options.extrudePath=null] - A 3D spline path along which the shape should be extruded. Bevels not supported for path extrusion.
-	 * @param {Object} [options.UVGenerator] - An object that provides UV generator functions for custom UV generation.
+	 * @param {ExtrudeGeometry~Options} [options] - The extrude settings.
 	 */
 	constructor( shapes = new Shape( [ new Vector2( 0.5, 0.5 ), new Vector2( - 0.5, 0.5 ), new Vector2( - 0.5, - 0.5 ), new Vector2( 0.5, - 0.5 ) ] ), options = {} ) {
 
@@ -862,5 +830,20 @@ function toJSON( shapes, options, data ) {
 
 }
 
+/**
+ * Represents the `options` type of the geometry's constructor.
+ *
+ * @typedef {Object} ExtrudeGeometry~Options
+ * @property {number} [curveSegments=12] - Number of points on the curves.
+ * @property {number} [steps=1] - Number of points used for subdividing segments along the depth of the extruded spline.
+ * @property {number} [depth=1] - Depth to extrude the shape.
+ * @property {boolean} [bevelEnabled=true] - Whether to beveling to the shape or not.
+ * @property {number} [bevelThickness=0.2] - How deep into the original shape the bevel goes.
+ * @property {number} [bevelSize=bevelThickness-0.1] - Distance from the shape outline that the bevel extends.
+ * @property {number} [bevelOffset=0] - Distance from the shape outline that the bevel starts.
+ * @property {number} [bevelSegments=3] - Number of bevel layers.
+ * @property {?Curve} [extrudePath=null] - A 3D spline path along which the shape should be extruded. Bevels not supported for path extrusion.
+ * @property {Object} [UVGenerator] - An object that provides UV generator functions for custom UV generation.
+ **/
 
 export { ExtrudeGeometry };

utils/docs/jsdoc.config.json

@@ -15,6 +15,8 @@
             "examples/jsm/animation",
             "examples/jsm/capabilities",
             "examples/jsm/controls",
+            "examples/jsm/curves",
+            "examples/jsm/environments",
             "examples/jsm/tsl",
             "src"
         ],

utils/docs/template/publish.js

@@ -333,7 +333,7 @@ function generateSourceFiles( sourceFiles, encoding = 'utf8' ) {
 
 }
 
-function buildClassNav( items, itemsSeen, linktoFn ) {
+function buildMainNav( items, itemsSeen, linktoFn ) {
 
 	const coreDirectory = 'src';
 	const addonsDirectory = 'examples/jsm';
@@ -363,7 +363,7 @@ function buildClassNav( items, itemsSeen, linktoFn ) {
 
 				}
 
-				itemNav += `<li data-name="${item.longname}">${linktoFn( item.longname, displayName.replace( /\b(module|event):/g, '' ) )}</li>`;
+				itemNav += `<li data-name="${item.name}">${linktoFn( item.longname, displayName.replace( /\b(module|event):/g, '' ) )}</li>`;
 
 				itemsSeen[ item.longname ] = true;
 
@@ -494,7 +494,6 @@ function pushNavItem( hierarchy, mainCategory, subCategory, itemNav ) {
 /**
  * Create the navigation sidebar.
  * @param {Object} members The members that will be used to create the sidebar.
- * @param {Array<Object>} members.classes
  * @return {string} The HTML for the navigation sidebar.
  */
 function buildNav( members ) {
@@ -502,7 +501,7 @@ function buildNav( members ) {
 	let nav = '';
 	const seen = {};
 
-	nav += buildClassNav( members.classes, seen, linkto );
+	nav += buildMainNav( [ ...members.classes, ...members.modules ], seen, linkto );
 	nav += buildGlobalsNav( members.globals, seen );
 
 	return nav;
@@ -757,10 +756,12 @@ exports.publish = ( taffyData, opts, tutorials ) => {
 
 	// set up the lists that we'll use to generate pages
 	const classes = taffy( members.classes );
+	const modules = taffy( members.modules );
 
 	Object.keys( helper.longnameToUrl ).forEach( longname => {
 
 		const myClasses = helper.find( classes, { longname: longname } );
+		const myModules = helper.find( modules, { longname: longname } );
 
 		if ( myClasses.length ) {
 
@@ -768,6 +769,12 @@ exports.publish = ( taffyData, opts, tutorials ) => {
 
 		}
 
+		if ( myModules.length ) {
+
+			generate( `${myModules[ 0 ].name}`, myModules, helper.longnameToUrl[ longname ] );
+
+		}
+
 	} );
 
 	// search

utils/docs/template/static/scripts/page.js

@@ -115,7 +115,7 @@ function updateNavigation() {
 	const filename = window.location.pathname.split( '/' ).pop();
 	const pagename = filename.split( '.' )[ 0 ];
 
-	let target = pagename;
+	let target = pagename.replace( 'module-', '' );
 
 	if ( pagename === 'global' ) {