Docs: More JSDoc. (#30662)

Author: Mugen87

examples/jsm/math/Capsule.js

@@ -2,74 +2,138 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * A capsule is essentially a cylinder with hemispherical caps at both ends.
+ * It can be thought of as a swept sphere, where a sphere is moved along a line segment.
+ *
+ * Capsules are often used as bounding volumes (next to AABBs and bounding spheres).
+ */
 class Capsule {
 
+	/**
+	 * Constructs a new capsule.
+	 *
+	 * @param {Vector3} [start] - The start vector.
+	 * @param {Vector3} [end] - The end vector.
+	 * @param {number} [radius=1] - The capsule's radius.
+	 */
 	constructor( start = new Vector3( 0, 0, 0 ), end = new Vector3( 0, 1, 0 ), radius = 1 ) {
 
+		/**
+		 * The start vector.
+		 *
+		 * @type {Vector3}
+		 */
 		this.start = start;
+
+		/**
+		 * The end vector.
+		 *
+		 * @type {Vector3}
+		 */
 		this.end = end;
+
+		/**
+		 * The capsule's radius.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.radius = radius;
 
 	}
 
+	/**
+	 * Returns a new capsule with copied values from this instance.
+	 *
+	 * @return {Capsule} A clone of this instance.
+	 */
 	clone() {
 
-		return new Capsule( this.start.clone(), this.end.clone(), this.radius );
+		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Sets the capsule components to the given values.
+	 * Please note that this method only copies the values from the given objects.
+	 *
+	 * @param {Vector3} start - The start vector.
+	 * @param {Vector3} end - The end vector
+	 * @param {number} radius - The capsule's radius.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	set( start, end, radius ) {
 
 		this.start.copy( start );
 		this.end.copy( end );
 		this.radius = radius;
 
+		return this;
+
 	}
 
+	/**
+	 * Copies the values of the given capsule to this instance.
+	 *
+	 * @param {Capsule} capsule - The capsule to copy.
+	 * @return {Capsule} A reference to this capsule.
+	 */
 	copy( capsule ) {
 
 		this.start.copy( capsule.start );
 		this.end.copy( capsule.end );
 		this.radius = capsule.radius;
 
+		return this;
+
 	}
 
+	/**
+	 * Returns the center point of this capsule.
+	 *
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The center point.
+	 */
 	getCenter( target ) {
 
 		return target.copy( this.end ).add( this.start ).multiplyScalar( 0.5 );
 
 	}
 
+	/**
+	 * Adds the given offset to this capsule, effectively moving it in 3D space.
+	 *
+	 * @param {Vector3} v - The offset that should be used to translate the capsule.
+	 * @return {Capsule} A reference to this capsule.
+	 */
 	translate( v ) {
 
 		this.start.add( v );
 		this.end.add( v );
 
-	}
-
-	checkAABBAxis( p1x, p1y, p2x, p2y, minx, maxx, miny, maxy, radius ) {
-
-		return (
-			( minx - p1x < radius || minx - p2x < radius ) &&
-			( p1x - maxx < radius || p2x - maxx < radius ) &&
-			( miny - p1y < radius || miny - p2y < radius ) &&
-			( p1y - maxy < radius || p2y - maxy < radius )
-		);
+		return this;
 
 	}
 
+	/**
+	 * Returns `true` if the given bounding box intersects with this capsule.
+	 *
+	 * @param {Box3} box - The bounding box to test.
+	 * @return {boolean} Whether the given bounding box intersects with this capsule.
+	 */
 	intersectsBox( box ) {
 
 		return (
-			this.checkAABBAxis(
+			checkAABBAxis(
 				this.start.x, this.start.y, this.end.x, this.end.y,
 				box.min.x, box.max.x, box.min.y, box.max.y,
 				this.radius ) &&
-			this.checkAABBAxis(
+			checkAABBAxis(
 				this.start.x, this.start.z, this.end.x, this.end.z,
 				box.min.x, box.max.x, box.min.z, box.max.z,
 				this.radius ) &&
-			this.checkAABBAxis(
+			checkAABBAxis(
 				this.start.y, this.start.z, this.end.y, this.end.z,
 				box.min.y, box.max.y, box.min.z, box.max.z,
 				this.radius )
@@ -79,4 +143,15 @@ class Capsule {
 
 }
 
+function checkAABBAxis( p1x, p1y, p2x, p2y, minx, maxx, miny, maxy, radius ) {
+
+	return (
+		( minx - p1x < radius || minx - p2x < radius ) &&
+		( p1x - maxx < radius || p2x - maxx < radius ) &&
+		( miny - p1y < radius || miny - p2y < radius ) &&
+		( p1y - maxy < radius || p2y - maxy < radius )
+	);
+
+}
+
 export { Capsule };

examples/jsm/math/ColorConverter.js

@@ -2,8 +2,22 @@ import { MathUtils } from 'three';
 
 const _hsl = {};
 
+/**
+ * A utility class with helper functions for color conversion.
+ *
+ * @hideconstructor
+ */
 class ColorConverter {
 
+	/**
+	 * Sets the given HSV color definition to the given color object.
+	 *
+	 * @param {Color} color - The color to set.
+	 * @param {number} h - The hue.
+	 * @param {number} s - The saturation.
+	 * @param {number} v - The value.
+	 * @return {Color} The update color.
+	 */
 	static setHSV( color, h, s, v ) {
 
 		// https://gist.github.com/xpansive/1337890#file-index-js
@@ -16,6 +30,13 @@ class ColorConverter {
 
 	}
 
+	/**
+	 * Returns a HSV color representation of the given color object.
+	 *
+	 * @param {Color} color - The color to get HSV values from.
+	 * @param {{h:number,s:number,v:number}} target - The target object that is used to store the method's result.
+	 * @return {{h:number,s:number,v:number}} The HSV color.
+	 */
 	static getHSV( color, target ) {
 
 		color.getHSL( _hsl );

examples/jsm/math/ColorSpaces.js

@@ -1,5 +1,7 @@
 import { LinearTransfer, Matrix3, SRGBTransfer } from 'three';
 
+/** @module ColorSpaces */
+
 // Reference: http://www.russellcottrell.com/photo/matrixCalculator.htm
 
 const P3_PRIMARIES = [ 0.680, 0.320, 0.265, 0.690, 0.150, 0.060 ];
@@ -24,9 +26,28 @@ const XYZ_TO_LINEAR_DISPLAY_P3 = /*@__PURE__*/ new Matrix3().set(
 	0.0358458, - 0.0761724, 0.9568845
 );
 
+/**
+ * Display-P3 color space.
+ *
+ * @type {string}
+ * @constant
+ */
 export const DisplayP3ColorSpace = 'display-p3';
+
+/**
+ * Display-P3-Linear color space.
+ *
+ * @type {string}
+ * @constant
+ */
 export const LinearDisplayP3ColorSpace = 'display-p3-linear';
 
+/**
+ * Implementation object for the Display-P3 color space.
+ *
+ * @type {module:ColorSpaces~ColorSpaceImpl}
+ * @constant
+ */
 export const DisplayP3ColorSpaceImpl = {
 	primaries: P3_PRIMARIES,
 	whitePoint: D65,
@@ -37,6 +58,12 @@ export const DisplayP3ColorSpaceImpl = {
 	outputColorSpaceConfig: { drawingBufferColorSpace: DisplayP3ColorSpace }
 };
 
+/**
+ * Implementation object for the Display-P3-Linear color space.
+ *
+ * @type {module:ColorSpaces~ColorSpaceImpl}
+ * @constant
+ */
 export const LinearDisplayP3ColorSpaceImpl = {
 	primaries: P3_PRIMARIES,
 	whitePoint: D65,
@@ -64,8 +91,20 @@ const XYZ_TO_LINEAR_REC2020 = /*@__PURE__*/ new Matrix3().set(
 	0.0176399, - 0.0427706, 0.9421031
 );
 
+/**
+ * Rec2020-Linear color space.
+ *
+ * @type {string}
+ * @constant
+ */
 export const LinearRec2020ColorSpace = 'rec2020-linear';
 
+/**
+ * Implementation object for the Rec2020-Linear color space.
+ *
+ * @type {module:ColorSpaces~ColorSpaceImpl}
+ * @constant
+ */
 export const LinearRec2020ColorSpaceImpl = {
 	primaries: REC2020_PRIMARIES,
 	whitePoint: D65,
@@ -74,3 +113,17 @@ export const LinearRec2020ColorSpaceImpl = {
 	fromXYZ: XYZ_TO_LINEAR_REC2020,
 	luminanceCoefficients: REC2020_LUMINANCE_COEFFICIENTS,
 };
+
+
+/**
+ * An object holding the color space implementation.
+ *
+ * @typedef {Object} module:ColorSpaces~ColorSpaceImpl
+ * @property {Array<number>} primaries - The primaries.
+ * @property {Array<number>} whitePoint - The white point.
+ * @property {Matrix3} toXYZ - A color space conversion matrix, converting to CIE XYZ.
+ * @property {Matrix3} fromXYZ - A color space conversion matrix, converting from CIE XYZ.
+ * @property {Array<number>} luminanceCoefficients - The luminance coefficients.
+ * @property {{unpackColorSpace:string}} [workingColorSpaceConfig] - The working color space config.
+ * @property {{drawingBufferColorSpace:string}} [outputColorSpaceConfig] - The drawing buffer color space config.
+ **/