Docs: Add more JSDoc. (#30641)

Author: Mugen87

examples/jsm/animation/AnimationClipCreator.js

@@ -7,8 +7,21 @@ import {
 	VectorKeyframeTrack
 } from 'three';
 
+/**
+ * A utility class with factory methods for creating basic animation clips.
+ *
+ * @hideconstructor
+ */
 class AnimationClipCreator {
 
+	/**
+	 * Creates an animation clip that rotates a 3D object 360 degress
+	 * in the given period of time around the given axis.
+	 *
+	 * @param {number} period - The duration of the animation.
+	 * @param {('x'|'y'|'z')} [axis='x'] - The axis of rotation.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateRotationAnimation( period, axis = 'x' ) {
 
 		const times = [ 0, period ], values = [ 0, 360 ];
@@ -21,6 +34,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that scales a 3D object from `0` to `1`
+	 * in the given period of time along the given axis.
+	 *
+	 * @param {number} period - The duration of the animation.
+	 * @param {('x'|'y'|'z')} [axis='x'] - The axis to scale the 3D object along.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateScaleAxisAnimation( period, axis = 'x' ) {
 
 		const times = [ 0, period ], values = [ 0, 1 ];
@@ -33,6 +54,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that translates a 3D object in a shake pattern
+	 * in the given period.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {number} shakeScale - The scale of the shake.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateShakeAnimation( duration, shakeScale ) {
 
 		const times = [], values = [], tmp = new Vector3();
@@ -55,6 +84,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that scales a 3D object in a pulse pattern
+	 * in the given period.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {number} pulseScale - The scale of the pulse.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreatePulsationAnimation( duration, pulseScale ) {
 
 		const times = [], values = [], tmp = new Vector3();
@@ -77,6 +114,12 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that toggles the visbility of a 3D object.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateVisibilityAnimation( duration ) {
 
 		const times = [ 0, duration / 2, duration ], values = [ true, false, true ];
@@ -89,6 +132,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that animates the `color` property of a 3D object's
+	 * material.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {Array<Color>} colors - An array of colors that should be sequentially animated.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateMaterialColorAnimation( duration, colors ) {
 
 		const times = [], values = [],

examples/jsm/animation/CCDIKSolver.js

@@ -25,36 +25,31 @@ const _axis = new Vector3();
 const _vector = new Vector3();
 const _matrix = new Matrix4();
 
-
 /**
- * CCD Algorithm
- *  - https://web.archive.org/web/20221206080850/https://sites.google.com/site/auraliusproject/ccd-algorithm
+ * This class solves the Inverse Kinematics Problem with a [CCD Algorithm]{@link https://web.archive.org/web/20221206080850/https://sites.google.com/site/auraliusproject/ccd-algorithm}.
  *
- * // ik parameter example
- * //
- * // target, effector, index in links are bone index in skeleton.bones.
- * // the bones relation should be
- * // <-- parent                                  child -->
- * // links[ n ], links[ n - 1 ], ..., links[ 0 ], effector
- * iks = [ {
- *	target: 1,
- *	effector: 2,
- *	links: [ { index: 5, limitation: new Vector3( 1, 0, 0 ) }, { index: 4, enabled: false }, { index : 3 } ],
- *	iteration: 10,
- *	minAngle: 0.0,
- *	maxAngle: 1.0,
- * } ];
+ * `CCDIKSolver` is designed to work with instances of {@link SkinnedMesh}.
  */
-
 class CCDIKSolver {
 
 	/**
-	 * @param {THREE.SkinnedMesh} mesh
-	 * @param {Array<Object>} iks
+	 * @param {SkinnedMesh} mesh - The skinned mesh.
+	 * @param {Array<CCDIKSolver~IK>} [iks=[]] - The IK objects.
 	 */
 	constructor( mesh, iks = [] ) {
 
+		/**
+		 * The skinned mesh.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.mesh = mesh;
+
+		/**
+		 * The IK objects.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.iks = iks;
 
 		this._initialQuaternions = [];
@@ -78,10 +73,10 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update all IK bones.
+	 * Updates all IK bones by solving the CCD algorithm.
 	 *
 	 * @param {number} [globalBlendFactor=1.0] - Blend factor applied if an IK chain doesn't have its own .blendFactor.
-	 * @return {CCDIKSolver}
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
 	update( globalBlendFactor = 1.0 ) {
 
@@ -98,11 +93,11 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update one IK bone
+	 * Updates one IK bone solving the CCD algorithm.
 	 *
-	 * @param {Object} ik parameter
-	 * @param {number} [overrideBlend=1.0] - If the ik object does not define .blendFactor, this value is used.
-	 * @return {CCDIKSolver}
+	 * @param {CCDIKSolver~IK} ik - The IK to update.
+	 * @param {number} [overrideBlend=1.0] - If the IK object does not define `blendFactor`, this value is used.
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
 	updateOne( ik, overrideBlend = 1.0 ) {
 
@@ -258,10 +253,10 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Creates Helper
+	 * Creates a helper for visualizing tehh CCDIK.
 	 *
-	 * @param {number} sphereSize
-	 * @return {CCDIKHelper}
+	 * @param {number} sphereSize - The sphere size.
+	 * @return {CCDIKHelper} The created helper.
 	 */
 	createHelper( sphereSize ) {
 
@@ -324,48 +319,86 @@ function setPositionOfBoneToAttributeArray( array, index, bone, matrixWorldInv )
 }
 
 /**
- * Visualize IK bones
+ * Helper for visualizing IK bones.
+ *
+ * @augments Object3D
  */
 class CCDIKHelper extends Object3D {
 
 	/**
-	 * @param {SkinnedMesh} mesh
- 	 * @param {Array<Object>} [iks=[]]
- 	 * @param {number} [sphereSize=0.25]
+	 * @param {SkinnedMesh} mesh - The skinned mesh.
+ 	 * @param {Array<CCDIKSolver~IK>} [iks=[]] - The IK objects.
+ 	 * @param {number} [sphereSize=0.25] - The sphere size.
 	 */
 	constructor( mesh, iks = [], sphereSize = 0.25 ) {
 
 		super();
 
+		/**
+		 * The skinned mesh this helper refers to.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.root = mesh;
+
+		/**
+		 * The IK objects.
+		 *
+		 * @type {Array<CCDIKSolver~IK>}
+		 */
 		this.iks = iks;
 
 		this.matrix.copy( mesh.matrixWorld );
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * The helpers sphere geometry.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.sphereGeometry = new SphereGeometry( sphereSize, 16, 8 );
 
+		/**
+		 * The material for the target spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.targetSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0xff8888 ),
 			depthTest: false,
 			depthWrite: false,
 			transparent: true
 		} );
 
+		/**
+		 * The material for the effector spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.effectorSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0x88ff88 ),
 			depthTest: false,
 			depthWrite: false,
 			transparent: true
 		} );
 
+		/**
+		 * The material for the link spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.linkSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0x8888ff ),
 			depthTest: false,
 			depthWrite: false,
 			transparent: true
 		} );
 
+		/**
+		 * A global line matreial.
+		 *
+		 * @type {LineBasicMaterial}
+		 */
 		this.lineMaterial = new LineBasicMaterial( {
 			color: new Color( 0xff0000 ),
 			depthTest: false,
@@ -377,11 +410,6 @@ class CCDIKHelper extends Object3D {
 
 	}
 
-	/**
-	 * Updates IK bones visualization.
-	 *
-	 * @param {boolean} force
-	 */
 	updateMatrixWorld( force ) {
 
 		const mesh = this.root;
@@ -446,7 +474,8 @@ class CCDIKHelper extends Object3D {
 	}
 
 	/**
-	 * Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
+	 * Frees the GPU-related resources allocated by this instance.
+	 * Call this method whenever this instance is no longer used in your app.
 	 */
 	dispose() {
 
@@ -531,4 +560,29 @@ class CCDIKHelper extends Object3D {
 
 }
 
+/**
+ * This type represents IK configuration objects.
+ *
+ * @typedef {Object} CCDIKSolver~IK
+ * @property {number} target - The target bone index which refers to a bone in the `Skeleton.bones` array.
+ * @property {number} effector - The effector bone index which refers to a bone in the `Skeleton.bones` array.
+ * @property {Array<CCDIKSolver~BoneLink>} links - An array of bone links.
+ * @property {number} [iteration=1] - Iteration number of calculation. Smaller is faster but less precise.
+ * @property {number} [minAngle] - Minimum rotation angle in a step in radians.
+ * @property {number} [maxAngle] - Minimum rotation angle in a step in radians.
+ * @property {number} [blendFactor] - The blend factor.
+ **/
+
+/**
+ * This type represents bone links.
+ *
+ * @typedef {Object} CCDIKSolver~BoneLink
+ * @property {number} index - The index of a linked bone which refers to a bone in the `Skeleton.bones` array.
+ * @property {number} [limitation] - Rotation axis.
+ * @property {number} [rotationMin] - Rotation minimum limit.
+ * @property {number} [rotationMax] - Rotation maximum limit.
+ * @property {boolean} [enabled=true] - Whether the link is enabled or not.
+ **/
+
+
 export { CCDIKSolver, CCDIKHelper };

examples/jsm/capabilities/WebGL.js

@@ -1,5 +1,15 @@
+/**
+ * A utility module with basic WebGL 2 capability testing.
+ *
+ * @hideconstructor
+ */
 class WebGL {
 
+	/**
+	 * Returns `true` if WebGL 2 is available.
+	 *
+	 * @return {boolean} Whether WebGL 2 is available or not.
+	 */
 	static isWebGL2Available() {
 
 		try {
@@ -15,6 +25,13 @@ class WebGL {
 
 	}
 
+	/**
+	 * Returns `true` if the given color space is available. This method can only be used
+	 * if WebGL 2 is supported.
+	 *
+	 * @param {string} colorSpace - The color space to test.
+	 * @return {boolean} Whether the given color space is available or not.
+	 */
 	static isColorSpaceAvailable( colorSpace ) {
 
 		try {
@@ -32,13 +49,21 @@ class WebGL {
 
 	}
 
+	/**
+	 * Returns a `div` element representing a formatted error message that can be appended in
+	 * web sites if WebGL 2 isn't supported.
+	 *
+	 * @return {HTMLDivElement} A `div` element representing a formatted error message that WebGL 2 isn't supported.
+	 */
 	static getWebGL2ErrorMessage() {
 
-		return this.getErrorMessage( 2 );
+		return this._getErrorMessage( 2 );
 
 	}
 
-	static getErrorMessage( version ) {
+	// private
+
+	static _getErrorMessage( version ) {
 
 		const names = {
 			1: 'WebGL',
@@ -105,7 +130,7 @@ class WebGL {
 
 		console.warn( 'getWebGLErrorMessage() has been deprecated and will be removed in r178. Use getWebGL2ErrorMessage() instead.' );
 
-		return this.getErrorMessage( 1 );
+		return this._getErrorMessage( 1 );
 
 	}