Docs: More JSDoc. (#30705)

* Docs: More JSDoc.

* VolumeSlice: Clean up.

examples/jsm/misc/ConvexObjectBreaker.js

@@ -6,39 +6,33 @@ import {
 } from 'three';
 import { ConvexGeometry } from '../geometries/ConvexGeometry.js';
 
+const _v1 = new Vector3();
+
 /**
- * @fileoverview This class can be used to subdivide a convex Geometry object into pieces.
- *
- * Usage:
+ * This class can be used to subdivide a convex Geometry object into pieces.
  *
  * Use the function prepareBreakableObject to prepare a Mesh object to be broken.
- *
- * Then, call the various functions to subdivide the object (subdivideByImpact, cutByPlane)
- *
+ * Then, call the various functions to subdivide the object (subdivideByImpact, cutByPlane).
  * Sub-objects that are product of subdivision don't need prepareBreakableObject to be called on them.
  *
  * Requisites for the object:
- *
- *  - Mesh object must have a buffer geometry and a material
- *
- *  - Vertex normals must be planar (not smoothed)
- *
- *  - The geometry must be convex (this is not checked in the library). You can create convex
- *  geometries with ConvexGeometry. The BoxGeometry, SphereGeometry and other convex primitives
- *  can also be used.
+ * - Mesh object must have a buffer geometry and a material.
+ * - Vertex normals must be planar (not smoothed).
+ * - The geometry must be convex (this is not checked in the library). You can create convex
+ * geometries with {@link ConvexGeometry}. The {@link BoxGeometry}, {@link SphereGeometry} and other
+ * convex primitives can also be used.
  *
  * Note: This lib adds member variables to object's userData member (see prepareBreakableObject function)
  * Use with caution and read the code when using with other libs.
- *
- * @param {double} minSizeForBreak Min size a debris can have to break.
- * @param {double} smallDelta Max distance to consider that a point belongs to a plane.
- *
 */
-
-const _v1 = new Vector3();
-
 class ConvexObjectBreaker {
 
+	/**
+	 * Constructs a new convex object breaker.
+	 *
+	 * @param {number} [minSizeForBreak=1.4] - Min size a debris can have to break.
+ 	 * @param {number} [smallDelta=0.0001] - Max distance to consider that a point belongs to a plane.
+	 */
 	constructor( minSizeForBreak = 1.4, smallDelta = 0.0001 ) {
 
 		this.minSizeForBreak = minSizeForBreak;
@@ -68,6 +62,15 @@ class ConvexObjectBreaker {
 
 	}
 
+	/**
+	 * Must be called for all 3D objects that should be breakable.
+	 *
+	 * @param {Object3D} object - The 3D object. It must have a convex geometry.
+	 * @param {number} mass - The 3D object's mass in kg. Must be greater than `0`.
+	 * @param {Vector3} velocity - The 3D object's velocity.
+	 * @param {Vector3} angularVelocity - The 3D object's angualar velocity.
+	 * @param {boolean} breakable - Whether the 3D object is breakable or not.
+	 */
 	prepareBreakableObject( object, mass, velocity, angularVelocity, breakable ) {
 
 		// object is a Object3d (normally a Mesh), must have a buffer geometry, and it must be convex.
@@ -82,11 +85,16 @@ class ConvexObjectBreaker {
 
 	}
 
-	/*
-	 * @param {int} maxRadialIterations Iterations for radial cuts.
-	 * @param {int} maxRandomIterations Max random iterations for not-radial cuts
+	/**
+	 * Subdivides the given 3D object into pieces by an impact (meaning another object hits
+	 * the given 3D object at a certain surface point).
 	 *
-	 * Returns the array of pieces
+	 * @param {Object3D} object - The 3D object to subdivide.
+	 * @param {Vector3} pointOfImpact - The point of impact.
+	 * @param {Vector3} normal - The impact normal.
+	 * @param {number} maxRadialIterations - Iterations for radial cuts.
+	 * @param {number} maxRandomIterations - Max random iterations for not-radial cuts.
+	 * @return {Array<Object3D>} The array of pieces.
 	 */
 	subdivideByImpact( object, pointOfImpact, normal, maxRadialIterations, maxRandomIterations ) {
 
@@ -168,6 +176,14 @@ class ConvexObjectBreaker {
 
 	}
 
+	/**
+	 * Subdivides the given 3D object into pieces by a plane.
+	 *
+	 * @param {Object3D} object - The 3D object to subdivide.
+	 * @param {Plane} plane - The plane to cut the 3D object.
+	 * @param {{object1:?Mesh,object2:?Mesh}} output - An object that stores the pieces.
+	 * @return {number} The number of pieces.
+	 */
 	cutByPlane( object, plane, output ) {
 
 		// Returns breakable objects in output.object1 and output.object2 members, the resulting 2 pieces of the cut.
@@ -449,6 +465,8 @@ class ConvexObjectBreaker {
 
 	}
 
+	// internal helpers
+
 	static transformFreeVector( v, m ) {
 
 		// input:

examples/jsm/misc/GPUComputationRenderer.js

@@ -11,10 +11,10 @@ import {
 import { FullScreenQuad } from '../postprocessing/Pass.js';
 
 /**
- * GPUComputationRenderer, based on SimulationRenderer by zz85
+ * GPUComputationRenderer, based on SimulationRenderer by @zz85.
  *
  * The GPUComputationRenderer uses the concept of variables. These variables are RGBA float textures that hold 4 floats
- * for each compute element (texel)
+ * for each compute element (texel).
  *
  * Each variable has a fragment shader that defines the computation made to obtain the variable in question.
  * You can use as many variables you need, and make dependencies so you can use textures of other variables in the shader
@@ -29,12 +29,11 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  * a common approach could be to use 'texture' prefixing the variable name; i.e texturePosition, textureVelocity...
  *
  * The size of the computation (sizeX * sizeY) is defined as 'resolution' automatically in the shader. For example:
+ * ```
  * #DEFINE resolution vec2( 1024.0, 1024.0 )
- *
- * -------------
- *
+ * ```
  * Basic use:
- *
+ * ```js
  * // Initialization...
  *
  * // Create computation renderer
@@ -62,7 +61,6 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  *		console.error( error );
   * }
  *
- *
  * // In each frame...
  *
  * // Compute!
@@ -73,12 +71,12 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  *
  * // Do your rendering
  * renderer.render( myScene, myCamera );
- *
- * -------------
+ * ```
  *
  * Also, you can use utility functions to create ShaderMaterial and perform computations (rendering between textures)
  * Note that the shaders can have multiple input textures.
  *
+ * ```js
  * const myFilter1 = gpuCompute.createShaderMaterial( myFilterFragmentShader1, { theTexture: { value: null } } );
  * const myFilter2 = gpuCompute.createShaderMaterial( myFilterFragmentShader2, { theTexture: { value: null } } );
  *
@@ -99,14 +97,16 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  * // And compute each frame, before rendering to screen:
  * gpuCompute.doRenderTarget( myFilter1, myRenderTarget );
  * gpuCompute.doRenderTarget( myFilter2, outputRenderTarget );
+ * ```
  */
-
 class GPUComputationRenderer {
 
 	/**
-	 * @param {number} sizeX Computation problem size is always 2d: sizeX * sizeY elements.
- 	 * @param {number} sizeY Computation problem size is always 2d: sizeX * sizeY elements.
- 	 * @param {WebGLRenderer} renderer The renderer
+	 * Constructs a new GPU computation renderer.
+	 *
+	 * @param {number} sizeX - Computation problem size is always 2d: sizeX * sizeY elements.
+ 	 * @param {number} sizeY - Computation problem size is always 2d: sizeX * sizeY elements.
+ 	 * @param {WebGLRenderer} renderer - The renderer.
 	 */
 	constructor( sizeX, sizeY, renderer ) {
 
@@ -124,6 +124,12 @@ class GPUComputationRenderer {
 
 		const quad = new FullScreenQuad( passThruShader );
 
+		/**
+		 * Sets the data type of the internal textures.
+		 *
+		 * @param {(FloatType|HalfFloatType)} type - The type to set.
+		 * @return {GPUComputationRenderer} A reference to this renderer.
+		 */
 		this.setDataType = function ( type ) {
 
 			dataType = type;
@@ -131,6 +137,14 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Adds a compute variable to the renderer.
+		 *
+		 * @param {string} variableName - The variable name.
+		 * @param {string} computeFragmentShader - The compute (fragment) shader source.
+		 * @param {Texture} initialValueTexture - The initial value texture.
+		 * @return {Object} The compute variable.
+		 */
 		this.addVariable = function ( variableName, computeFragmentShader, initialValueTexture ) {
 
 			const material = this.createShaderMaterial( computeFragmentShader );
@@ -153,12 +167,23 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Sets variable dependencies.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @param {Array<Object>} dependencies - Ohter compute variables that represents the dependencies.
+		 */
 		this.setVariableDependencies = function ( variable, dependencies ) {
 
 			variable.dependencies = dependencies;
 
 		};
 
+		/**
+		 * Initializes the renderer.
+		 *
+		 * @return {?string} Returns `null` if no errors are detected. Otherwise returns the error message.
+		 */
 		this.init = function () {
 
 			if ( renderer.capabilities.maxVertexTextures === 0 ) {
@@ -227,6 +252,9 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Executes the compute. This method is usually called in the animation loop.
+		 */
 		this.compute = function () {
 
 			const currentTextureIndex = this.currentTextureIndex;
@@ -260,18 +288,34 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Returns the current render target for the given compute variable.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @return {WebGLRenderTarget} The current render target.
+		 */
 		this.getCurrentRenderTarget = function ( variable ) {
 
 			return variable.renderTargets[ this.currentTextureIndex ];
 
 		};
 
+		/**
+		 * Returns the alternate render target for the given compute variable.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @return {WebGLRenderTarget} The alternate render target.
+		 */
 		this.getAlternateRenderTarget = function ( variable ) {
 
 			return variable.renderTargets[ this.currentTextureIndex === 0 ? 1 : 0 ];
 
 		};
 
+		/**
+		 * Frees all internal resources. Call this method if you don't need the
+		 * renderer anymore.
+		 */
 		this.dispose = function () {
 
 			quad.dispose();
@@ -303,6 +347,11 @@ class GPUComputationRenderer {
 
 		}
 
+		/**
+		 * Adds a resolution defined for the given material shader.
+		 *
+		 * @param {Object} materialShader - The material shader.
+		 */
 		this.addResolutionDefine = addResolutionDefine;
 
 
@@ -327,6 +376,17 @@ class GPUComputationRenderer {
 
 		this.createShaderMaterial = createShaderMaterial;
 
+		/**
+		 * Creates a new render target from the given paramters.
+		 *
+		 * @param {number} sizeXTexture - The width of the render target.
+		 * @param {number} sizeYTexture - The height of the render target.
+		 * @param {number} wrapS - The wrapS value.
+		 * @param {number} wrapT - The wrapS value.
+		 * @param {number} minFilter - The minFilter value.
+		 * @param {number} magFilter - The magFilter value.
+		 * @return {WebGLRenderTarget} The new render target.
+		 */
 		this.createRenderTarget = function ( sizeXTexture, sizeYTexture, wrapS, wrapT, minFilter, magFilter ) {
 
 			sizeXTexture = sizeXTexture || sizeX;
@@ -352,6 +412,11 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Creates a new data texture.
+		 *
+		 * @return {DataTexture} The new data texture.
+		 */
 		this.createTexture = function () {
 
 			const data = new Float32Array( sizeX * sizeY * 4 );
@@ -361,12 +426,14 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Renders the given texture into the given render target.
+		 *
+		 * @param {Texture} input - The input.
+		 * @param {WebGLRenderTarget} output - The output.
+		 */
 		this.renderTexture = function ( input, output ) {
 
-			// Takes a texture, and render out in rendertarget
-			// input = Texture
-			// output = RenderTarget
-
 			passThruUniforms.passThruTexture.value = input;
 
 			this.doRenderTarget( passThruShader, output );
@@ -375,6 +442,14 @@ class GPUComputationRenderer {
 
 		};
 
+
+		/**
+		 * Renders the given material into the given render target
+		 * with a full-screen pass.
+		 *
+		 * @param {Material} material - The material.
+		 * @param {WebGLRenderTarget} output - The output.
+		 */
 		this.doRenderTarget = function ( material, output ) {
 
 			const currentRenderTarget = renderer.getRenderTarget();

examples/jsm/misc/Gyroscope.js

@@ -12,8 +12,19 @@ const _translationWorld = new Vector3();
 const _quaternionWorld = new Quaternion();
 const _scaleWorld = new Vector3();
 
+/**
+ * A special type of 3D object that takes a position from the scene graph hierarchy
+ * but uses its local rotation as world rotation. It works like real-world gyroscope -
+ * you can move it around using hierarchy while its orientation stays fixed with
+ * respect to the world.
+ *
+ * @augments Object3D
+ */
 class Gyroscope extends Object3D {
 
+	/**
+	 * Constructs a new gyroscope.
+	 */
 	constructor() {
 
 		super();

examples/jsm/misc/MD2Character.js

@@ -10,33 +10,111 @@ import {
 } from 'three';
 import { MD2Loader } from '../loaders/MD2Loader.js';
 
+/**
+ * This class represents a management component for animated MD2
+ * character assets.
+ */
 class MD2Character {
 
+	/**
+	 * Constructs a new MD2 character.
+	 */
 	constructor() {
 
+		/**
+		 * The mesh scale.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.scale = 1;
+
+		/**
+		 * The FPS
+		 *
+		 * @type {number}
+		 * @default 6
+		 */
 		this.animationFPS = 6;
 
+		/**
+		 * The root 3D object
+		 *
+		 * @type {Object3D}
+		 */
 		this.root = new Object3D();
 
+		/**
+		 * The body mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshBody = null;
+
+		/**
+		 * The weapon mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshWeapon = null;
 
+		/**
+		 * The body skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsBody = [];
+
+		/**
+		 * The weapon skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsWeapon = [];
 
+		/**
+		 * The weapon meshes.
+		 *
+		 * @type {Array<Mesh>}
+		 */
 		this.weapons = [];
 
-		this.activeAnimation = null;
-
+		/**
+		 * The name of the active animation clip.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
+		this.activeAnimationClipName = null;
+
+		/**
+		 * The animation mixer.
+		 *
+		 * @type {?AnimationMixer}
+		 * @default null
+		 */
 		this.mixer = null;
 
+		/**
+		 * The `onLoad` callback function.
+		 *
+		 * @type {Function}
+		 */
 		this.onLoadComplete = function () {};
 
+		// internal
+
 		this.loadCounter = 0;
 
 	}
 
+	/**
+	 * Loads the character model for the given config.
+	 *
+	 * @param {Object} config - The config which defines the model and textures paths.
+	 */
 	loadParts( config ) {
 
 		const scope = this;
@@ -156,6 +234,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the animation playback rate.
+	 *
+	 * @param {number} rate - The playback rate to set.
+	 */
 	setPlaybackRate( rate ) {
 
 		if ( rate !== 0 ) {
@@ -170,6 +253,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the wireframe material flag.
+	 *
+	 * @param {boolean} wireframeEnabled - Whether to enable wireframe rendering or not.
+	 */
 	setWireframe( wireframeEnabled ) {
 
 		if ( wireframeEnabled ) {
@@ -186,6 +274,12 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the skin defined by the given skin index. This will result in a different texture
+	 * for the body mesh.
+	 *
+	 * @param {number} index - The skin index.
+	 */
 	setSkin( index ) {
 
 		if ( this.meshBody && this.meshBody.material.wireframe === false ) {
@@ -196,6 +290,12 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the weapon defined by the given weapon index. This will result in a different weapon
+	 * hold by the character.
+	 *
+	 * @param {number} index - The weapon index.
+	 */
 	setWeapon( index ) {
 
 		for ( let i = 0; i < this.weapons.length; i ++ ) this.weapons[ i ].visible = false;
@@ -213,6 +313,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the defined animation clip as the active animation.
+	 *
+	 * @param {string} clipName - The name of the animation clip.
+	 */
 	setAnimation( clipName ) {
 
 		if ( this.meshBody ) {
@@ -240,6 +345,9 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Synchronizes the weapon with the body animation.
+	 */
 	syncWeaponAnimation() {
 
 		const clipName = this.activeClipName;
@@ -265,6 +373,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh. Must be called inside the animation loop.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	update( delta ) {
 
 		if ( this.mixer ) this.mixer.update( delta );

examples/jsm/misc/MD2CharacterComplex.js

@@ -10,45 +10,147 @@ import {
 import { MD2Loader } from '../loaders/MD2Loader.js';
 import { MorphBlendMesh } from '../misc/MorphBlendMesh.js';
 
+/**
+ * This class represents a management component for animated MD2
+ * character assets. It provides a larger API compared to {@link MD2Character}.
+ */
 class MD2CharacterComplex {
 
+	/**
+	 * Constructs a new MD2 character.
+	 */
 	constructor() {
 
+		/**
+		 * The mesh scale.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.scale = 1;
 
-		// animation parameters
-
+		/**
+		 * The FPS
+		 *
+		 * @type {number}
+		 * @default 6
+		 */
 		this.animationFPS = 6;
-		this.transitionFrames = 15;
 
-		// movement model parameters
+		/**
+		 * The transition frames.
+		 *
+		 * @type {number}
+		 * @default 15
+		 */
+		this.transitionFrames = 15;
 
+		/**
+		 * The character's maximum speed.
+		 *
+		 * @type {number}
+		 * @default 275
+		 */
 		this.maxSpeed = 275;
+
+		/**
+		 * The character's maximum reverse speed.
+		 *
+		 * @type {number}
+		 * @default - 275
+		 */
 		this.maxReverseSpeed = - 275;
 
+		/**
+		 * The character's front acceleration.
+		 *
+		 * @type {number}
+		 * @default 600
+		 */
 		this.frontAcceleration = 600;
+
+		/**
+		 * The character's back acceleration.
+		 *
+		 * @type {number}
+		 * @default 600
+		 */
 		this.backAcceleration = 600;
 
+		/**
+		 * The character's front decceleration.
+		 *
+		 * @type {number}
+		 * @default 600
+		 */
 		this.frontDecceleration = 600;
 
+		/**
+		 * The character's angular speed.
+		 *
+		 * @type {number}
+		 * @default 2.5
+		 */
 		this.angularSpeed = 2.5;
 
-		// rig
-
+		/**
+		 * The root 3D object
+		 *
+		 * @type {Object3D}
+		 */
 		this.root = new Object3D();
 
+		/**
+		 * The body mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshBody = null;
+
+		/**
+		 * The weapon mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshWeapon = null;
 
+		/**
+		 * The movement contorls.
+		 *
+		 * @type {Object}
+		 * @default null
+		 */
 		this.controls = null;
 
-		// skins
-
+		/**
+		 * The body skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsBody = [];
+
+		/**
+		 * The weapon skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsWeapon = [];
 
+		/**
+		 * The weapon meshes.
+		 *
+		 * @type {Array<Mesh>}
+		 */
 		this.weapons = [];
 
+		/**
+		 * The current skin.
+		 *
+		 * @type {Texture}
+		 * @default undefined
+		 */
 		this.currentSkin = undefined;
 
 		//
@@ -79,6 +181,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Toggles shadow casting and receiving on the character's meshes.
+	 *
+	 * @param {boolean} enable - Whether to enable shadows or not.
+	 */
 	enableShadows( enable ) {
 
 		for ( let i = 0; i < this.meshes.length; i ++ ) {
@@ -90,6 +197,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Toggles visibility on the character's meshes.
+	 *
+	 * @param {boolean} enable - Whether the character is visible or not.
+	 */
 	setVisible( enable ) {
 
 		for ( let i = 0; i < this.meshes.length; i ++ ) {
@@ -101,6 +213,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Shares certain resources from a different character model.
+	 *
+	 * @param {MD2CharacterComplex} original - The original MD2 character.
+	 */
 	shareParts( original ) {
 
 		this.animations = original.animations;
@@ -143,6 +260,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Loads the character model for the given config.
+	 *
+	 * @param {Object} config - The config which defines the model and textures paths.
+	 */
 	loadParts( config ) {
 
 		const scope = this;
@@ -241,6 +363,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the animation playback rate.
+	 *
+	 * @param {number} rate - The playback rate to set.
+	 */
 	setPlaybackRate( rate ) {
 
 		if ( this.meshBody ) this.meshBody.duration = this.meshBody.baseDuration / rate;
@@ -248,6 +375,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the wireframe material flag.
+	 *
+	 * @param {boolean} wireframeEnabled - Whether to enable wireframe rendering or not.
+	 */
 	setWireframe( wireframeEnabled ) {
 
 		if ( wireframeEnabled ) {
@@ -264,6 +396,12 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the skin defined by the given skin index. This will result in a different texture
+	 * for the body mesh.
+	 *
+	 * @param {number} index - The skin index.
+	 */
 	setSkin( index ) {
 
 		if ( this.meshBody && this.meshBody.material.wireframe === false ) {
@@ -275,6 +413,12 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the weapon defined by the given weapon index. This will result in a different weapon
+	 * hold by the character.
+	 *
+	 * @param {number} index - The weapon index.
+	 */
 	setWeapon( index ) {
 
 		for ( let i = 0; i < this.weapons.length; i ++ ) this.weapons[ i ].visible = false;
@@ -297,6 +441,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the defined animation clip as the active animation.
+	 *
+	 * @param {string} animationName - The name of the animation clip.
+	 */
 	setAnimation( animationName ) {
 
 		if ( animationName === this.activeAnimation || ! animationName ) return;
@@ -336,6 +485,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh. Must be called inside the animation loop.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	updateAnimations( delta ) {
 
 		let mix = 1;
@@ -367,6 +521,9 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Updates the animation state based on the control inputs.
+	 */
 	updateBehaviors() {
 
 		const controls = this.controls;
@@ -476,6 +633,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Transforms the character model based on the control input.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	updateMovementModel( delta ) {
 
 		function exponentialEaseOut( k ) {

examples/jsm/misc/MorphAnimMesh.js

@@ -4,31 +4,69 @@ import {
 	Mesh
 } from 'three';
 
+/**
+ * A special type of an animated mesh with a simple interface
+ * for animation playback. It allows to playback just one animation
+ * without any transitions or fading between animation changes.
+ *
+ * @augments Mesh
+ */
 class MorphAnimMesh extends Mesh {
 
+	/**
+	 * Constructs a new morph anim mesh.
+	 *
+	 * @param {BufferGeometry} [geometry] - The mesh geometry.
+	 * @param {Material|Array<Material>} [material] - The mesh material.
+	 */
 	constructor( geometry, material ) {
 
 		super( geometry, material );
 
 		this.type = 'MorphAnimMesh';
 
+		/**
+		 * The internal animation mixer.
+		 *
+		 * @type {AnimationMixer}
+		 */
 		this.mixer = new AnimationMixer( this );
+
+		/**
+		 * The current active animation action.
+		 *
+		 * @type {?AnimationAction}
+		 * @default null
+		 */
 		this.activeAction = null;
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "forward".
+	 */
 	setDirectionForward() {
 
 		this.mixer.timeScale = 1.0;
 
 	}
 
+	/**
+	 * Sets the animation playback directio to "backward".
+	 */
 	setDirectionBackward() {
 
 		this.mixer.timeScale = - 1.0;
 
 	}
 
+	/**
+	 * Plays the defined animation clip. The implementation assumes the animation
+	 * clips are stored in {@link Object3D#animations} or the geometry.
+	 *
+	 * @param {string} label - The name of the animation clip.
+	 * @param {number} fps - The FPS of the animation clip.
+	 */
 	playAnimation( label, fps ) {
 
 		if ( this.activeAction ) {
@@ -54,6 +92,11 @@ class MorphAnimMesh extends Mesh {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh. Must be called inside the animation loop.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	updateAnimation( delta ) {
 
 		this.mixer.update( delta );

examples/jsm/misc/MorphBlendMesh.js

@@ -3,13 +3,38 @@ import {
 	Mesh
 } from 'three';
 
+/**
+ * A special type of an animated mesh with a more advanced interface
+ * for animation playback. Unlike {@link MorphAnimMesh}. It allows to
+ * playback more than one morph animation at the same time but without
+ * fading options.
+ *
+ * @augments Mesh
+ */
 class MorphBlendMesh extends Mesh {
 
+	/**
+	 * Constructs a new morph blend mesh.
+	 *
+	 * @param {BufferGeometry} [geometry] - The mesh geometry.
+	 * @param {Material|Array<Material>} [material] - The mesh material.
+	 */
 	constructor( geometry, material ) {
 
 		super( geometry, material );
 
+		/**
+		 * A dictionary of animations.
+		 *
+		 * @type {Object<string,Object>}
+		 */
 		this.animationsMap = {};
+
+		/**
+		 * A list of animations.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.animationsList = [];
 
 		// prepare default animation
@@ -29,6 +54,14 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Creates a new animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} start - The start time.
+	 * @param {number} end - The end time.
+	 * @param {number} fps - The FPS.
+	 */
 	createAnimation( name, start, end, fps ) {
 
 		const animation = {
@@ -60,6 +93,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Automatically creates animations based on the values in
+	 * {@link Mesh#morphTargetDictionary}.
+	 *
+	 * @param {number} fps - The FPS of all animations.
+	 */
 	autoCreateAnimations( fps ) {
 
 		const pattern = /([a-z]+)_?(\d+)/i;
@@ -104,6 +143,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "forward" for the
+	 * defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	setAnimationDirectionForward( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -117,6 +162,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "backward" for the
+	 * defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	setAnimationDirectionBackward( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -130,6 +181,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the FPS to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} fps - The FPS to set.
+	 */
 	setAnimationFPS( name, fps ) {
 
 		const animation = this.animationsMap[ name ];
@@ -143,6 +200,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the duration to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} duration - The duration to set.
+	 */
 	setAnimationDuration( name, duration ) {
 
 		const animation = this.animationsMap[ name ];
@@ -156,6 +219,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the weight to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} weight - The weight to set.
+	 */
 	setAnimationWeight( name, weight ) {
 
 		const animation = this.animationsMap[ name ];
@@ -168,6 +237,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the time to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} time - The time to set.
+	 */
 	setAnimationTime( name, time ) {
 
 		const animation = this.animationsMap[ name ];
@@ -180,6 +255,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Returns the time for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @return {number} The time.
+	 */
 	getAnimationTime( name ) {
 
 		let time = 0;
@@ -196,6 +277,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Returns the duration for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @return {number} The duration.
+	 */
 	getAnimationDuration( name ) {
 
 		let duration = - 1;
@@ -212,6 +299,11 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Plays the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	playAnimation( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -229,6 +321,11 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Stops the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	stopAnimation( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -241,6 +338,11 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Updates the animations of thie mesh.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	update( delta ) {
 
 		for ( let i = 0, il = this.animationsList.length; i < il; i ++ ) {

examples/jsm/misc/ProgressiveLightMap.js

@@ -2,7 +2,7 @@ import { DoubleSide, FloatType, HalfFloatType, Mesh, MeshBasicMaterial, MeshPhon
 import { potpack } from '../libs/potpack.module.js';
 
 /**
- * Progressive Light Map Accumulator, by [zalo](https://github.com/zalo/)
+ * Progressive Light Map Accumulator, by [zalo]{@link https://github.com/zalo/}.
  *
  * To use, simply construct a `ProgressiveLightMap` object,
  * `plmap.addObjectsToLightMap(object)` an array of semi-static
@@ -13,17 +13,37 @@ import { potpack } from '../libs/potpack.module.js';
  * This should begin accumulating lightmaps which apply to
  * your objects, so you can start jittering lighting to achieve
  * the texture-space effect you're looking for.
+ *
+ * This class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, import from `ProgressiveLightMapGPU.js`.
  */
 class ProgressiveLightMap {
 
 	/**
-	 * @param {WebGLRenderer} renderer An instance of WebGLRenderer.
- 	 * @param {number} [res=1024] The side-long dimension of you total lightmap.
+	 * Constructs a new progressive light map.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+ 	 * @param {number} [res=1024] - The side-long dimension of the total lightmap.
 	 */
 	constructor( renderer, res = 1024 ) {
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {WebGLRenderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * The side-long dimension of the total lightmap.
+		 *
+		 * @type {number}
+		 * @default 1024
+		 */
 		this.res = res;
+
+		// internals
+
 		this.lightMapContainers = [];
 		this.scene = new Scene();
 		this.buffer1Active = false;
@@ -76,7 +96,8 @@ class ProgressiveLightMap {
 
 	/**
 	 * Sets these objects' materials' lightmaps and modifies their uv1's.
-	 * @param {Object3D} objects An array of objects and lights to set up your lightmap.
+	 *
+	 * @param {Array<Object3D>} objects - An array of objects and lights to set up your lightmap.
 	 */
 	addObjectsToLightMap( objects ) {
 
@@ -142,10 +163,11 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * This function renders each mesh one at a time into their respective surface maps
-	 * @param {Camera} camera Standard Rendering Camera
-	 * @param {number} blendWindow When >1, samples will accumulate over time.
-	 * @param {boolean} blurEdges  Whether to fix UV Edges via blurring
+	 * This function renders each mesh one at a time into their respective surface maps.
+	 *
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 * @param {number} [blendWindow=100] - When >1, samples will accumulate over time.
+	 * @param {boolean} [blurEdges=true] - Whether to fix UV Edges via blurring.
 	 */
 	update( camera, blendWindow = 100, blurEdges = true ) {
 
@@ -215,10 +237,11 @@ class ProgressiveLightMap {
 
 	}
 
-	/** DEBUG
-	 * Draw the lightmap in the main scene.  Call this after adding the objects to it.
-	 * @param {boolean} visible Whether the debug plane should be visible
-	 * @param {Vector3} position Where the debug plane should be drawn
+	/**
+	 * Draws the lightmap in the main scene. Call this after adding the objects to it.
+	 *
+	 * @param {boolean} visible - Whether the debug plane should be visible
+	 * @param {Vector3} [position] - Where the debug plane should be drawn
 	*/
 	showDebugLightmap( visible, position = undefined ) {
 
@@ -251,9 +274,11 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * INTERNAL Creates the Blurring Plane
-	 * @param {number} res The square resolution of this object's lightMap.
-	 * @param {WebGLRenderTexture} lightMap The lightmap to initialize the plane with.
+	 * Creates the Blurring Plane.
+	 *
+	 * @private
+	 * @param {number} res - The square resolution of this object's lightMap.
+	 * @param {WebGLRenderTarget} [lightMap] - The lightmap to initialize the plane with.
 	 */
 	_initializeBlurPlane( res, lightMap = null ) {
 

examples/jsm/misc/ProgressiveLightMapGPU.js

@@ -4,7 +4,7 @@ import { add, float, mix, output, sub, texture, uniform, uv, vec2, vec4 } from '
 import { potpack } from '../libs/potpack.module.js';
 
 /**
- * Progressive Light Map Accumulator, by [zalo](https://github.com/zalo/)
+ * Progressive Light Map Accumulator, by [zalo]{@link https://github.com/zalo/}.
  *
  * To use, simply construct a `ProgressiveLightMap` object,
  * `plmap.addObjectsToLightMap(object)` an array of semi-static
@@ -15,16 +15,31 @@ import { potpack } from '../libs/potpack.module.js';
  * This should begin accumulating lightmaps which apply to
  * your objects, so you can start jittering lighting to achieve
  * the texture-space effect you're looking for.
+ *
+ * This class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, import from `ProgressiveLightMap.js`.
  */
 class ProgressiveLightMap {
 
 	/**
-	 * @param {WebGPURenderer} renderer An instance of WebGPURenderer.
-	 * @param {number} [resolution=1024] The side-long dimension of you total lightmap.
+	 * @param {WebGPURenderer} renderer - The renderer.
+	 * @param {number} [resolution=1024] - The side-long dimension of the total lightmap.
 	 */
 	constructor( renderer, resolution = 1024 ) {
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {WebGPURenderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * The side-long dimension of the total lightmap.
+		 *
+		 * @type {number}
+		 * @default 1024
+		 */
 		this.resolution = resolution;
 
 		this._lightMapContainers = [];
@@ -57,7 +72,8 @@ class ProgressiveLightMap {
 
 	/**
 	 * Sets these objects' materials' lightmaps and modifies their uv1's.
-	 * @param {Object3D} objects An array of objects and lights to set up your lightmap.
+	 *
+	 * @param {Array<Object3D>} objects - An array of objects and lights to set up your lightmap.
 	 */
 	addObjectsToLightMap( objects ) {
 
@@ -150,10 +166,11 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * This function renders each mesh one at a time into their respective surface maps
-	 * @param {Camera} camera Standard Rendering Camera
-	 * @param {number} blendWindow When >1, samples will accumulate over time.
-	 * @param {boolean} blurEdges  Whether to fix UV Edges via blurring
+	 * This function renders each mesh one at a time into their respective surface maps.
+	 *
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 * @param {number} [blendWindow=100] - When >1, samples will accumulate over time.
+	 * @param {boolean} [blurEdges=true] - Whether to fix UV Edges via blurring.
 	 */
 	update( camera, blendWindow = 100, blurEdges = true ) {
 
@@ -213,9 +230,10 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * Draw the lightmap in the main scene.  Call this after adding the objects to it.
-	 * @param {boolean} visible Whether the debug plane should be visible.
-	 * @param {Vector3} position Where the debug plane should be drawn.
+	 * Draws the lightmap in the main scene. Call this after adding the objects to it.
+	 *
+	 * @param {boolean} visible - Whether the debug plane should be visible
+	 * @param {Vector3} [position] - Where the debug plane should be drawn
 	*/
 	showDebugLightmap( visible, position = null ) {
 
@@ -254,6 +272,8 @@ class ProgressiveLightMap {
 
 	/**
 	 * Creates the Blurring Plane.
+	 *
+	 * @private
 	 */
 	_initializeBlurPlane() {
 

examples/jsm/misc/RollerCoaster.js

@@ -8,8 +8,19 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * A procedural roller coaster geometry.
+ *
+ * @augments BufferGeometry
+ */
 class RollerCoasterGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Curve} curve - The curve to genereate the geometry along.
+ 	 * @param {number} divisions - The number of divisions which defines the detail of the geometry.
+	 */
 	constructor( curve, divisions ) {
 
 		super();
@@ -222,8 +233,19 @@ class RollerCoasterGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural roller coaster lifters geometry.
+ *
+ * @augments BufferGeometry
+ */
 class RollerCoasterLiftersGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Curve} curve - The curve to genereate the geometry along.
+ 	 * @param {number} divisions - The number of divisions which defines the detail of the geometry.
+	 */
 	constructor( curve, divisions ) {
 
 		super();
@@ -398,8 +420,19 @@ class RollerCoasterLiftersGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural roller coaster shadow geometry.
+ *
+ * @augments BufferGeometry
+ */
 class RollerCoasterShadowGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Curve} curve - The curve to genereate the geometry along.
+ 	 * @param {number} divisions - The number of divisions which defines the detail of the geometry.
+	 */
 	constructor( curve, divisions ) {
 
 		super();
@@ -470,8 +503,16 @@ class RollerCoasterShadowGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural sky geometry.
+ *
+ * @augments BufferGeometry
+ */
 class SkyGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 */
 	constructor() {
 
 		super();
@@ -503,8 +544,19 @@ class SkyGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural trees geometry.
+ *
+ * @augments BufferGeometry
+ */
 class TreesGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Mesh} landscape - A mesh representing the landscape. Trees will be positioned
+	 * randomly on the landscape's surface.
+	 */
 	constructor( landscape ) {
 
 		super();

examples/jsm/misc/Timer.js

@@ -1,5 +1,22 @@
+/**
+ * This class is an alternative to {@link Clock} with a different API design and behavior.
+ * The goal is to avoid the conceptual flaws that became apparent in `Clock` over time.
+ *
+ * - `Timer` has an `update()` method that updates its internal state. That makes it possible to
+ * call `getDelta()` and `getElapsed()` multiple times per simulation step without getting different values.
+ * - The class can make use of the Page Visibility API to avoid large time delta values when the app
+ * is inactive (e.g. tab switched or browser hidden).
+ *
+ * ```js
+ * const timer = new Timer();
+ * timer.connect( document ); // use Page Visibility API
+ * ```
+ */
 class Timer {
 
+	/**
+	 * Constructs a new timer.
+	 */
 	constructor() {
 
 		this._previousTime = 0;
@@ -16,6 +33,13 @@ class Timer {
 
 	}
 
+	/**
+	 * Connect the timer to the given document.Calling this method is not mandatory to
+	 * use the timer but enables the usage of the Page Visibility API to avoid large time
+	 * delta values.
+	 *
+	 * @param {Document} document - The document.
+	 */
 	connect( document ) {
 
 		this._document = document;
@@ -32,6 +56,9 @@ class Timer {
 
 	}
 
+	/**
+	 * Disconnects the timer from the DOM and also disables the usage of the Page Visibility API.
+	 */
 	disconnect() {
 
 		if ( this._pageVisibilityHandler !== null ) {
@@ -45,24 +72,46 @@ class Timer {
 
 	}
 
+	/**
+	 * Returns the time delta in seconds.
+	 *
+	 * @return {number} The time delta in second.
+	 */
 	getDelta() {
 
 		return this._delta / 1000;
 
 	}
 
+	/**
+	 * Returns the elapsed time in seconds.
+	 *
+	 * @return {number} The elapsed time in second.
+	 */
 	getElapsed() {
 
 		return this._elapsed / 1000;
 
 	}
 
+	/**
+	 * Returns the timescale.
+	 *
+	 * @return {number} The timescale.
+	 */
 	getTimescale() {
 
 		return this._timescale;
 
 	}
 
+	/**
+	 * Sets the given timescale which scale the time delta computation
+	 * in `update()`.
+	 *
+	 * @param {number} timescale - The timescale to set.
+	 * @return {Timer} A reference to this timer.
+	 */
 	setTimescale( timescale ) {
 
 		this._timescale = timescale;
@@ -71,6 +120,11 @@ class Timer {
 
 	}
 
+	/**
+	 * Resets the time computation for the current simulation step.
+	 *
+	 * @return {Timer} A reference to this timer.
+	 */
 	reset() {
 
 		this._currentTime = now() - this._startTime;
@@ -79,14 +133,26 @@ class Timer {
 
 	}
 
+	/**
+	 * Can be used to free all internal resources. Usually called when
+	 * the timer instance isn't required anymore.
+	 */
 	dispose() {
 
 		this.disconnect();
 
-		return this;
-
 	}
 
+	/**
+	 * Updates the internal state of the timer. This method should be called
+	 * once per simulation step and before you perform queries against the timer
+	 * (e.g. via `getDelta()`).
+	 *
+	 * @param {number} timestamp - The current time in milliseconds. Can be obtained
+	 * from the `requestAnimationFrame` callback argument. If not provided, the current
+	 * time will be determined with `performance.now`.
+	 * @return {Timer} A reference to this timer.
+	 */
 	update( timestamp ) {
 
 		if ( this._pageVisibilityHandler !== null && this._document.hidden === true ) {
@@ -109,8 +175,19 @@ class Timer {
 
 }
 
+/**
+ * A special version of a timer with a fixed time delta value.
+ * Can be useful for testing and debugging purposes.
+ *
+ * @augments Timer
+ */
 class FixedTimer extends Timer {
 
+	/**
+	 * Constructs a new timer.
+	 *
+	 * @param {number} [fps=60] - The fixed FPS of this timer.
+	 */
 	constructor( fps = 60 ) {
 
 		super();

examples/jsm/misc/TubePainter.js

@@ -9,6 +9,19 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * @classdesc This module can be used to paint tube-like meshes
+ * along a sequence of points. This module is used in a XR
+ * painter demo.
+ *
+ * ```js
+ * const painter = new TubePainter();
+ * scene.add( painter.mesh );
+ * ```
+ *
+ * @name TubePainter
+ * @class
+ */
 function TubePainter() {
 
 	const BUFFER_SIZE = 1000000 * 3;
@@ -190,10 +203,50 @@ function TubePainter() {
 	}
 
 	return {
+		/**
+		 * The "painted" tube mesh. Must be added to the scene.
+		 *
+		 * @name TubePainter#mesh
+		 * @type {Mesh}
+		 */
 		mesh: mesh,
+
+		/**
+		 * Moves the current painting position to the given value.
+		 *
+		 * @method
+		 * @name TubePainter#moveTo
+		 * @param {Vector3} position The new painting position.
+		 */
 		moveTo: moveTo,
+
+		/**
+		 * Draw a stroke from the current position to the given one.
+		 * This method extends the tube while drawing with the XR
+		 * controllers.
+		 *
+		 * @method
+		 * @name TubePainter#lineTo
+		 * @param {Vector3} position The destination position.
+		 */
 		lineTo: lineTo,
+
+		/**
+		 * Sets the size of newly rendered tube segments.
+		 *
+		 * @method
+		 * @name TubePainter#setSize
+		 * @param {number} size The size.
+		 */
 		setSize: setSize,
+
+		/**
+		 * Updates the internal goemetry buffers so the new painted
+		 * segments are rendered.
+		 *
+		 * @method
+		 * @name TubePainter#update
+		 */
 		update: update
 	};
 

examples/jsm/misc/Volume.js

@@ -6,44 +6,61 @@ import {
 import { VolumeSlice } from '../misc/VolumeSlice.js';
 
 /**
- * This class had been written to handle the output of the NRRD loader.
- * It contains a volume of data and information about it.
- * For now it only handles 3 dimensional data.
- * See the webgl_loader_nrrd.html example and the loaderNRRD.js file to see how to use this class.
- * @class
+ * This class had been written to handle the output of the {@link NRRDLoader}.
+ * It contains a volume of data and information about it. For now it only handles 3 dimensional data.
  */
 class Volume {
 
 	/**
-	 * @param   {number}        xLength         Width of the volume
-	 * @param   {number}        yLength         Length of the volume
-	 * @param   {number}        zLength         Depth of the volume
-	 * @param   {string}        type            The type of data (uint8, uint16, ...)
-	 * @param   {ArrayBuffer}   arrayBuffer     The buffer with volume data
+	 * Constructs a new volume.
+	 *
+	 * @param {number} [xLength] - Width of the volume.
+	 * @param {number} [yLength] - Length of the volume.
+	 * @param {number} [zLength] - Depth of the volume.
+	 * @param {string} [type] - The type of data (uint8, uint16, ...).
+	 * @param {ArrayBuffer} [arrayBuffer] - The buffer with volume data.
 	 */
 	constructor( xLength, yLength, zLength, type, arrayBuffer ) {
 
 		if ( xLength !== undefined ) {
 
 			/**
-			 * @member {number} xLength Width of the volume in the IJK coordinate system
+			 * Width of the volume in the IJK coordinate system.
+			 *
+			 * @type {number}
+			 * @default 1
 			 */
 			this.xLength = Number( xLength ) || 1;
+
 			/**
-			 * @member {number} yLength Height of the volume in the IJK coordinate system
+			 * Height of the volume in the IJK coordinate system.
+			 *
+			 * @type {number}
+			 * @default 1
 			 */
 			this.yLength = Number( yLength ) || 1;
+
 			/**
-			 * @member {number} zLength Depth of the volume in the IJK coordinate system
+			 * Depth of the volume in the IJK coordinate system.
+			 *
+			 * @type {number}
+			 * @default 1
 			 */
 			this.zLength = Number( zLength ) || 1;
+
 			/**
-			 * @member {Array<string>} The order of the Axis dictated by the NRRD header
+			 * The order of the Axis dictated by the NRRD header
+			 *
+			 * @type {Array<string>}
 			 */
 			this.axisOrder = [ 'x', 'y', 'z' ];
+
 			/**
-			 * @member {TypedArray} data Data of the volume
+			 * The data of the volume.
+			 *
+			 * @type {TypedArray}
 			 */
+			this.data;
 
 			switch ( type ) {
 
@@ -129,25 +146,34 @@ class Volume {
 		}
 
 		/**
-		 * @member {Array}  spacing Spacing to apply to the volume from IJK to RAS coordinate system
+		 * Spacing to apply to the volume from IJK to RAS coordinate system
+		 *
+		 * @type {Array<number>}
 		 */
 		this.spacing = [ 1, 1, 1 ];
+
 		/**
-		 * @member {Array}  offset Offset of the volume in the RAS coordinate system
+		 * Offset of the volume in the RAS coordinate system
+		 *
+		 * @type {Array<number>}
 		 */
 		this.offset = [ 0, 0, 0 ];
+
 		/**
-		 * @member {Martrix3} matrix The IJK to RAS matrix
+		 * The IJK to RAS matrix.
+		 *
+		 * @type {Martrix3}
 		 */
 		this.matrix = new Matrix3();
 		this.matrix.identity();
+
 		/**
-		 * @member {Martrix3} inverseMatrix The RAS to IJK matrix
-		 */
-		/**
-		 * @member {number} lowerThreshold The voxels with values under this threshold won't appear in the slices.
-		 *                      If changed, geometryNeedsUpdate is automatically set to true on all the slices associated to this volume
+		 * The RAS to IJK matrix.
+		 *
+		 * @type {Martrix3}
 		 */
+		this.inverseMatrix = new Matrix3();
+
 		let lowerThreshold = - Infinity;
 		Object.defineProperty( this, 'lowerThreshold', {
 			get: function () {
@@ -155,6 +181,14 @@ class Volume {
 				return lowerThreshold;
 
 			},
+			/**
+			 * The voxels with values under this threshold won't appear in the slices.
+			 * If changed, geometryNeedsUpdate is automatically set to true on all the slices associated to this volume.
+			 *
+			 * @name Volume#lowerThreshold
+			 * @type {number}
+			 * @param {number} value
+			 */
 			set: function ( value ) {
 
 				lowerThreshold = value;
@@ -166,10 +200,7 @@ class Volume {
 
 			}
 		} );
-		/**
-		 * @member {number} upperThreshold The voxels with values over this threshold won't appear in the slices.
-		 *                      If changed, geometryNeedsUpdate is automatically set to true on all the slices associated to this volume
-		 */
+
 		let upperThreshold = Infinity;
 		Object.defineProperty( this, 'upperThreshold', {
 			get: function () {
@@ -177,6 +208,14 @@ class Volume {
 				return upperThreshold;
 
 			},
+			/**
+			 * The voxels with values over this threshold won't appear in the slices.
+			 * If changed, geometryNeedsUpdate is automatically set to true on all the slices associated to this volume
+			 *
+			 * @name Volume#upperThreshold
+			 * @type {number}
+			 * @param {number} value
+			 */
 			set: function ( value ) {
 
 				upperThreshold = value;
@@ -191,33 +230,38 @@ class Volume {
 
 
 		/**
-		 * @member {Array} sliceList The list of all the slices associated to this volume
+		 * The list of all the slices associated to this volume
+		 *
+		 * @type {Array}
 		 */
 		this.sliceList = [];
 
-
 		/**
-		 * @member {boolean} segmentation in segmentation mode, it can load 16-bits nrrds correctly
+		 * Whether to use segmentation mode or not.
+		 * It can load 16-bits nrrds correctly.
+		 *
+		 * @type {boolean}
+		 * @default false
 		 */
 		this.segmentation = false;
 
 
 		/**
-		 * @member {Array} RASDimensions This array holds the dimensions of the volume in the RAS space
+		 * This array holds the dimensions of the volume in the RAS space
+		 *
+		 * @type {Array<number>}
 		 */
-
-
+		this.RASDimensions = [];
 
 	}
 
 	/**
-	 * Shortcut for data[access(i,j,k)]
+	 * Shortcut for data[access(i,j,k)].
 	 *
-	 * @memberof Volume
-	 * @param {number} i    First coordinate
-	 * @param {number} j    Second coordinate
-	 * @param {number} k    Third coordinate
-	 * @returns {number}  value in the data array
+	 * @param {number} i - First coordinate.
+	 * @param {number} j - Second coordinate.
+	 * @param {number} k - Third coordinate.
+	 * @returns {number} The value in the data array.
 	 */
 	getData( i, j, k ) {
 
@@ -226,13 +270,12 @@ class Volume {
 	}
 
 	/**
-	 * Compute the index in the data array corresponding to the given coordinates in IJK system
+	 * Compute the index in the data array corresponding to the given coordinates in IJK system.
 	 *
-	 * @memberof Volume
-	 * @param {number} i    First coordinate
-	 * @param {number} j    Second coordinate
-	 * @param {number} k    Third coordinate
-	 * @returns {number}  index
+	 * @param {number} i - First coordinate.
+	 * @param {number} j - Second coordinate.
+	 * @param {number} k - Third coordinate.
+	 * @returns {number} The index.
 	 */
 	access( i, j, k ) {
 
@@ -241,11 +284,10 @@ class Volume {
 	}
 
 	/**
-	 * Retrieve the IJK coordinates of the voxel corresponding of the given index in the data
+	 * Retrieve the IJK coordinates of the voxel corresponding of the given index in the data.
 	 *
-	 * @memberof Volume
-	 * @param {number} index index of the voxel
-	 * @returns {Array}  [x,y,z]
+	 * @param {number} index - Index of the voxel.
+	 * @returns {Array<number>} The IJK coordinates as `[x,y,z]`.
 	 */
 	reverseAccess( index ) {
 
@@ -257,15 +299,12 @@ class Volume {
 	}
 
 	/**
-	 * Apply a function to all the voxels, be careful, the value will be replaced
+	 * Apply a function to all the voxels, be careful, the value will be replaced.
 	 *
-	 * @memberof Volume
-	 * @param {Function} functionToMap A function to apply to every voxel, will be called with the following parameters :
-	 *                                 value of the voxel
-	 *                                 index of the voxel
-	 *                                 the data (TypedArray)
-	 * @param {Object}   context    You can specify a context in which call the function, default if this Volume
-	 * @returns {Volume}   this
+	 * @param {Function} functionToMap A function to apply to every voxel, will be called with the following parameters:
+	 * value of the voxel, index of the voxel, the data (TypedArray).
+	 * @param {Object} context - You can specify a context in which call the function, default if this Volume.
+	 * @returns {Volume} A reference to this instance.
 	 */
 	map( functionToMap, context ) {
 
@@ -283,12 +322,12 @@ class Volume {
 	}
 
 	/**
-	 * Compute the orientation of the slice and returns all the information relative to the geometry such as sliceAccess, the plane matrix (orientation and position in RAS coordinate) and the dimensions of the plane in both coordinate system.
+	 * Compute the orientation of the slice and returns all the information relative to the geometry such as sliceAccess,
+	 * the plane matrix (orientation and position in RAS coordinate) and the dimensions of the plane in both coordinate system.
 	 *
-	 * @memberof Volume
-	 * @param {string}            axis  the normal axis to the slice 'x' 'y' or 'z'
-	 * @param {number}            RASIndex the index of the slice
-	 * @returns {Object} an object containing all the useful information on the geometry of the slice
+	 * @param {('x'|'y'|'z')} axis - The normal axis to the slice.
+	 * @param {number} RASIndex - The index of the slice.
+	 * @returns {Object} An object containing all the useful information on the geometry of the slice.
 	 */
 	extractPerpendicularPlane( axis, RASIndex ) {
 
@@ -411,10 +450,9 @@ class Volume {
 	 * Returns a slice corresponding to the given axis and index.
 	 * The coordinate are given in the Right Anterior Superior coordinate format.
 	 *
-	 * @memberof Volume
-	 * @param {string}            axis  the normal axis to the slice 'x' 'y' or 'z'
-	 * @param {number}            index the index of the slice
-	 * @returns {VolumeSlice} the extracted slice
+	 * @param {('x'|'y'|'z')} axis - The normal axis to the slice.
+	 * @param {number} index - The index of the slice.
+	 * @returns {VolumeSlice} The extracted slice.
 	 */
 	extractSlice( axis, index ) {
 
@@ -425,11 +463,10 @@ class Volume {
 	}
 
 	/**
-	 * Call repaint on all the slices extracted from this volume
+	 * Call repaint on all the slices extracted from this volume.
 	 *
 	 * @see {@link VolumeSlice#repaint}
-	 * @memberof Volume
-	 * @returns {Volume} this
+	 * @returns {Volume} A reference to this volume.
 	 */
 	repaintAllSlices() {
 
@@ -444,10 +481,9 @@ class Volume {
 	}
 
 	/**
-	 * Compute the minimum and the maximum of the data in the volume
+	 * Compute the minimum and the maximum of the data in the volume.
 	 *
-	 * @memberof Volume
-	 * @returns {Array} [min,max]
+	 * @returns {Array<number>} The min/max data as `[min,max]`.
 	 */
 	computeMinMax() {
 

examples/jsm/misc/VolumeSlice.js

@@ -10,34 +10,45 @@ import {
 } from 'three';
 
 /**
- * This class has been made to hold a slice of a volume data
- * @class
+ * This class has been made to hold a slice of a volume data.
+ *
  * @see {@link Volume}
  */
 class VolumeSlice {
 
 	/**
- 	 * @param {Volume} volume     The associated volume
- 	 * @param {number} [index=0]  The index of the slice
- 	 * @param {string} [axis='z'] For now only 'x', 'y' or 'z' but later it will change to a normal vector
+	 * Constructs a new volume slice.
+	 *
+ 	 * @param {Volume} volume - The associated volume.
+ 	 * @param {number} [index=0] - The index of the slice.
+ 	 * @param {('x'|'y'|'z')} [axis='z'] - For now only 'x', 'y' or 'z' but later it will change to a normal vector.
 	 */
-	constructor( volume, index, axis ) {
+	constructor( volume, index = 0, axis = 'z' ) {
 
 		const slice = this;
+
 		/**
-		 * @member {Volume} volume The associated volume
+		 * The associated volume.
+		 *
+		 * @type {Volume}
 		 */
 		this.volume = volume;
-		/**
-		 * @member {number} index The index of the slice, if changed, will automatically call updateGeometry at the next repaint
-		 */
-		index = index || 0;
+
 		Object.defineProperty( this, 'index', {
 			get: function () {
 
 				return index;
 
 			},
+			/**
+			 * The index of the slice, if changed, will automatically call updateGeometry at the next repaint.
+			 *
+			 * @name VolumeSlice#index
+			 * @type {number}
+			 * @default 0
+			 * @param {number} value
+			 * @return {number}
+			 */
 			set: function ( value ) {
 
 				index = value;
@@ -46,25 +57,42 @@ class VolumeSlice {
 
 			}
 		} );
-		/**
-		 * @member {string} axis The normal axis
-		 */
-		this.axis = axis || 'z';
 
 		/**
-		 * @member {HTMLCanvasElement} canvas The final canvas used for the texture
+		 * The normal axis.
+		 *
+		 * @type {('x'|'y'|'z')}
 		 */
+		this.axis = axis;
+
 		/**
-		 * @member {CanvasRenderingContext2D} ctx Context of the canvas
+		 * The final canvas used for the texture.
+		 *
+		 * @type {HTMLCanvasElement}
 		 */
 		this.canvas = document.createElement( 'canvas' );
+
 		/**
-		 * @member {HTMLCanvasElement} canvasBuffer The intermediary canvas used to paint the data
+		 * The rendering context of the canvas.
+		 *
+		 * @type {CanvasRenderingContext2D}
 		 */
+		this.ctx;
+
 		/**
-		 * @member {CanvasRenderingContext2D} ctxBuffer Context of the canvas buffer
+		 * The intermediary canvas used to paint the data.
+		 *
+		 * @type {HTMLCanvasElement}
 		 */
 		this.canvasBuffer = document.createElement( 'canvas' );
+
+		/**
+		 * The rendering context of the canvas buffer,
+		 *
+		 * @type {CanvasRenderingContext2D}
+		 */
+		this.ctxBuffer;
+
 		this.updateGeometry();
 
 
@@ -74,39 +102,52 @@ class VolumeSlice {
 		canvasMap.wrapS = canvasMap.wrapT = ClampToEdgeWrapping;
 		canvasMap.colorSpace = SRGBColorSpace;
 		const material = new MeshBasicMaterial( { map: canvasMap, side: DoubleSide, transparent: true } );
+
 		/**
-		 * @member {Mesh} mesh The mesh ready to get used in the scene
+		 * The mesh ready to get used in the scene.
+		 *
+		 * @type {Mesh}
 		 */
 		this.mesh = new Mesh( this.geometry, material );
 		this.mesh.matrixAutoUpdate = false;
+
 		/**
-		 * @member {boolean} geometryNeedsUpdate If set to true, updateGeometry will be triggered at the next repaint
+		 * If set to `true`, `updateGeometry()` will be triggered at the next repaint.
+		 *
+		 * @type {boolean}
+		 * @default true
 		 */
 		this.geometryNeedsUpdate = true;
 		this.repaint();
 
 		/**
-		 * @member {number} iLength Width of slice in the original coordinate system, corresponds to the width of the buffer canvas
+		 * Width of slice in the original coordinate system, corresponds to the width of the buffer canvas.
+		 *
+		 * @type {number}
+		 * @default 0
 		 */
+		this.iLength = 0;
 
 		/**
-		 * @member {number} jLength Height of slice in the original coordinate system, corresponds to the height of the buffer canvas
+		 * Height of slice in the original coordinate system, corresponds to the height of the buffer canvas.
+		 *
+		 * @type {number}
+		 * @default 0
 		 */
+		this.jLength = 0;
 
 		/**
-		 * @member {Function} sliceAccess Function that allow the slice to access right data
+		 * Function that allow the slice to access right data.
+		 *
+		 * @type {?Function}
 		 * @see {@link Volume#extractPerpendicularPlane}
-		 * @param {number} i The first coordinate
-		 * @param {number} j The second coordinate
-		 * @returns {number} the index corresponding to the voxel in volume.data of the given position in the slice
 		 */
-
+		this.sliceAccess = null;
 
 	}
 
 	/**
-	 * Refresh the texture and the geometry if geometryNeedsUpdate is set to true
-	 * @memberof VolumeSlice
+	 * Refresh the texture and the geometry if geometryNeedsUpdate is set to `true`.
 	 */
 	repaint() {
 
@@ -191,9 +232,8 @@ class VolumeSlice {
 	}
 
 	/**
-	 * Refresh the geometry according to axis and index
+	 * Refresh the geometry according to axis and index.
 	 * @see {@link Volume#extractPerpendicularPlane}
-	 * @memberof VolumeSlice
 	 */
 	updateGeometry() {
 

examples/jsm/physics/AmmoPhysics.js

@@ -1,5 +1,5 @@
 /**
- * @classdesc  Can be used to include Ammo.js as a Physics engine into
+ * @classdesc Can be used to include Ammo.js as a Physics engine into
  * `three.js` apps. Make sure to include `ammo.wasm.js` first:
  * ```
  * <script src="jsm/libs/ammo.wasm.js"></script>

utils/docs/jsdoc.config.json

@@ -28,6 +28,7 @@
             "examples/jsm/lines",
             "examples/jsm/materials",
             "examples/jsm/math",
+            "examples/jsm/misc",
             "examples/jsm/modifiers",
             "examples/jsm/objects",
             "examples/jsm/physics",
@@ -42,12 +43,13 @@
             "src/renderers/common/extras/PMREMGenerator.js",
             "examples/jsm/helpers/LightProbeHelperGPU.js",
             "examples/jsm/helpers/TextureHelperGPU.js",
+            "examples/jsm/libs",
             "examples/jsm/lines/webgpu",
             "examples/jsm/materials/LDrawConditionalLineNodeMaterial.js",
+            "examples/jsm/misc/ProgressiveLightMapGPU.js",
             "examples/jsm/modifiers/CurveModifierGPU.js",
             "examples/jsm/objects/Water2.js",
             "examples/jsm/objects/Water2Mesh.js",
-            "examples/jsm/libs",
             "examples/jsm/offscreen",
             "examples/jsm/utils/ShadowMapViewerGPU.js"
         ]