Docs: More JSDoc. (#30705)

* Docs: More JSDoc.

* VolumeSlice: Clean up.

Author: Mugen87

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,13 +124,27 @@ 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;
 			return this;
 
 		};
 
+		/**
+		 * 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();