Docs: More JSDoc. (#30702)

examples/jsm/physics/AmmoPhysics.js

@@ -1,3 +1,18 @@
+/**
+ * @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>
+ * ```
+ * It is then possible to initialize the API via:
+ * ```js
+ * const physics = await AmmoPhysics();
+ * ```
+ *
+ * @name AmmoPhysics
+ * @class
+ * @hideconstructor
+ */
 async function AmmoPhysics() {
 
 	if ( 'Ammo' in window === false ) {
@@ -265,8 +280,40 @@ async function AmmoPhysics() {
 	setInterval( step, 1000 / frameRate );
 
 	return {
+		/**
+		 * Adds the given scene to this physics simulation. Only meshes with a
+		 * `physics` object in their {@link Object3D#userData} field will be honored.
+		 * The object can be used to store the mass of the mesh. E.g.:
+		 * ```js
+		 * box.userData.physics = { mass: 1 };
+		 * ```
+		 *
+		 * @method
+		 * @name AmmoPhysics#addScene
+		 * @param {Object3D} scene The scene or any type of 3D object to add.
+		 */
 		addScene: addScene,
+
+		/**
+		 * Adds the given mesh to this physics simulation.
+		 *
+		 * @method
+		 * @name AmmoPhysics#addMesh
+		 * @param {Mesh} mesh The mesh to add.
+		 * @param {number} [mass=0] The mass in kg of the mesh.
+		 */
 		addMesh: addMesh,
+
+		/**
+		 * Set the position of the given mesh which is part of the pyhsics simulation. Calling this
+		 * method will reset the current simulated velocity of the mesh.
+		 *
+		 * @method
+		 * @name AmmoPhysics#setMeshPosition
+		 * @param {Mesh} mesh The mesh to update the position for.
+		 * @param {Vector3} position - The new position.
+		 * @param {number} [index=0] - If the mesh is instanced, the index represents the instanced ID.
+		 */
 		setMeshPosition: setMeshPosition
 		// addCompoundMesh
 	};

examples/jsm/physics/JoltPhysics.js

@@ -57,6 +57,19 @@ function setupCollisionFiltering( settings ) {
 
 }
 
+/**
+ * @classdesc Can be used to include Jolt as a Physics engine into
+ * `three.js` apps. The API can be initialized via:
+ * ```js
+ * const physics = await JoltPhysics();
+ * ```
+ * The component automatically imports Jolt from a CDN so make sure
+ * to use the component with an active Internet connection.
+ *
+ * @name JoltPhysics
+ * @class
+ * @hideconstructor
+ */
 async function JoltPhysics() {
 
 	if ( Jolt === null ) {
@@ -270,9 +283,44 @@ async function JoltPhysics() {
 	setInterval( step, 1000 / frameRate );
 
 	return {
+		/**
+		 * Adds the given scene to this physics simulation. Only meshes with a
+		 * `physics` object in their {@link Object3D#userData} field will be honored.
+		 * The object can be used to store the mass and restitution of the mesh. E.g.:
+		 * ```js
+		 * box.userData.physics = { mass: 1, restitution: 0 };
+		 * ```
+		 *
+		 * @method
+		 * @name JoltPhysics#addScene
+		 * @param {Object3D} scene The scene or any type of 3D object to add.
+		 */
 		addScene: addScene,
+
+		/**
+		 * Adds the given mesh to this physics simulation.
+		 *
+		 * @method
+		 * @name JoltPhysics#addMesh
+		 * @param {Mesh} mesh The mesh to add.
+		 * @param {number} [mass=0] The mass in kg of the mesh.
+		 * @param {number} [restitution=0] The restitution/friction of the mesh.
+		 */
 		addMesh: addMesh,
+
+		/**
+		 * Set the position of the given mesh which is part of the pyhsics simulation. Calling this
+		 * method will reset the current simulated velocity of the mesh.
+		 *
+		 * @method
+		 * @name JoltPhysics#setMeshPosition
+		 * @param {Mesh} mesh The mesh to update the position for.
+		 * @param {Vector3} position - The new position.
+		 * @param {number} [index=0] - If the mesh is instanced, the index represents the instanced ID.
+		 */
 		setMeshPosition: setMeshPosition,
+
+		// NOOP
 		setMeshVelocity: setMeshVelocity
 	};
 

examples/jsm/physics/RapierPhysics.js

@@ -54,6 +54,19 @@ function getShape( geometry ) {
 
 }
 
+/**
+ * @classdesc Can be used to include Rapier as a Physics engine into
+ * `three.js` apps. The API can be initialized via:
+ * ```js
+ * const physics = await RapierPhysics();
+ * ```
+ * The component automatically imports Rapier from a CDN so make sure
+ * to use the component with an active Internet connection.
+ *
+ * @name RapierPhysics
+ * @class
+ * @hideconstructor
+ */
 async function RapierPhysics() {
 
 	if ( RAPIER === null ) {
@@ -229,9 +242,52 @@ async function RapierPhysics() {
 	setInterval( step, 1000 / frameRate );
 
 	return {
+		/**
+		 * Adds the given scene to this physics simulation. Only meshes with a
+		 * `physics` object in their {@link Object3D#userData} field will be honored.
+		 * The object can be used to store the mass and restitution of the mesh. E.g.:
+		 * ```js
+		 * box.userData.physics = { mass: 1, restitution: 0 };
+		 * ```
+		 *
+		 * @method
+		 * @name RapierPhysics#addScene
+		 * @param {Object3D} scene The scene or any type of 3D object to add.
+		 */
 		addScene: addScene,
+
+		/**
+		 * Adds the given mesh to this physics simulation.
+		 *
+		 * @method
+		 * @name RapierPhysics#addMesh
+		 * @param {Mesh} mesh The mesh to add.
+		 * @param {number} [mass=0] The mass in kg of the mesh.
+		 * @param {number} [restitution=0] The restitution/friction of the mesh.
+		 */
 		addMesh: addMesh,
+
+		/**
+		 * Set the position of the given mesh which is part of the pyhsics simulation. Calling this
+		 * method will reset the current simulated velocity of the mesh.
+		 *
+		 * @method
+		 * @name RapierPhysics#setMeshPosition
+		 * @param {Mesh} mesh The mesh to update the position for.
+		 * @param {Vector3} position - The new position.
+		 * @param {number} [index=0] - If the mesh is instanced, the index represents the instanced ID.
+		 */
 		setMeshPosition: setMeshPosition,
+
+		/**
+		 * Set the velocity of the given mesh which is part of the pyhsics simulation.
+		 *
+		 * @method
+		 * @name RapierPhysics#setMeshVelocity
+		 * @param {Mesh} mesh The mesh to update the velocity for.
+		 * @param {Vector3} velocity - The new velocity.
+		 * @param {number} [index=0] - If the mesh is instanced, the index represents the instanced ID.
+		 */
 		setMeshVelocity: setMeshVelocity
 	};
 

examples/jsm/transpiler/Transpiler.js

@@ -1,12 +1,43 @@
+/**
+ * A class that transpiles shader code from one language into another.
+ *
+ * `Transpiler` can only be used to convert GLSL into TSL right now. It is intended
+ * to support developers when they want to migrate their custom materials from the
+ * current to the new node-based material system.
+ */
 class Transpiler {
 
+	/**
+	 * Constructs a new transpiler.
+	 *
+	 * @param {GLSLDecoder} decoder - The GLSL decoder.
+	 * @param {TSLEncoder} encoder - The TSL encoder.
+	 */
 	constructor( decoder, encoder ) {
 
+		/**
+		 * The GLSL decoder. This component parse GLSL and produces
+		 * a language-independent AST for further processing.
+		 *
+		 * @type {GLSLDecoder}
+		 */
 		this.decoder = decoder;
+
+		/**
+		 * The TSL encoder. It takes the AST and emits TSL code.
+		 *
+		 * @type {TSLEncoder}
+		 */
 		this.encoder = encoder;
 
 	}
 
+	/**
+	 * Parses the given GLSL source and returns TSL syntax.
+	 *
+	 * @param {string} source - The GLSL source.
+	 * @return {string} The TSL code.
+	 */
 	parse( source ) {
 
 		return this.encoder.emit( this.decoder.parse( source ) );

examples/jsm/tsl/lighting/TiledLightsNode.js

@@ -34,6 +34,13 @@ export const circleIntersectsAABB = /*@__PURE__*/ Fn( ( [ circleCenter, radius,
 const _vector3 = /*@__PURE__*/ new Vector3();
 const _size = /*@__PURE__*/ new Vector2();
 
+/**
+ * A custom version of `LightsNode` implementing tiled lighting. This node is used in
+ * {@link TiledLighting} to overwrite the renderer's default lighting with
+ * a custom implementation.
+ *
+ * @augments LightsNode
+ */
 class TiledLightsNode extends LightsNode {
 
 	static get type() {
@@ -42,6 +49,12 @@ class TiledLightsNode extends LightsNode {
 
 	}
 
+	/**
+	 * Constructs a new tiled lights node.
+	 *
+	 * @param {number} [maxLights=1024] - The maximum number of lights.
+	 * @param {number} [tileSize=32] - The tile size.
+	 */
 	constructor( maxLights = 1024, tileSize = 32 ) {
 
 		super();
@@ -49,7 +62,20 @@ class TiledLightsNode extends LightsNode {
 		this.materialLights = [];
 		this.tiledLights = [];
 
+		/**
+		 * The maximum number of lights.
+		 *
+		 * @type {number}
+		 * @default 1024
+		 */
 		this.maxLights = maxLights;
+
+		/**
+		 * The tile size.
+		 *
+		 * @type {number}
+		 * @default 32
+		 */
 		this.tileSize = tileSize;
 
 		this._bufferSize = null;

examples/jsm/tsl/math/Bayer.js

@@ -1,8 +1,21 @@
 import { TextureLoader } from 'three';
 import { Fn, int, ivec2, textureLoad } from 'three/tsl';
 
+/** @module Bayer */
+
 let bayer16Texture = null;
 
+/**
+ * This TSL function can be used to sample a Bayer16 texture which is a 16x16 texture with a Bayer Matrix pattern.
+ * It can be used for dithering effects but also as an alternative to blue-noise. When used with Ray Marching
+ * specifically in {@link VolumeNodeMaterial#offsetNode}, it reduces banding problem, thus being able to use
+ * fewer steps without affecting the visuals as much.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec2>} uv - The uv to sample the bayer16 texture.
+ * @return {Node<vec4>} The sampled bayer value.
+ */
 export const bayer16 = Fn( ( [ uv ] ) => {
 
 	if ( bayer16Texture === null ) {

examples/jsm/tsl/utils/Raymarching.js

@@ -1,5 +1,7 @@
 import { varying, vec4, modelWorldMatrixInverse, cameraPosition, positionGeometry, float, Fn, Loop, max, min, vec2, vec3 } from 'three/tsl';
 
+/** @module Raymarching */
+
 const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
 
 	const box_min = vec3( - 0.5 );
@@ -21,7 +23,8 @@ const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
 } );
 
 /**
- * Performs raymarching box-area using the specified number of steps and a callback function.
+ * TSL function for performing raymarching in a box-area using the specified number of steps
+ * and a callback function.
  *
  * ```js
  * RaymarchingBox( count, ( { positionRay } ) => {
@@ -33,7 +36,6 @@ const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
  * @function
  * @param {number|Node} steps - The number of steps for raymarching.
  * @param {Function|FunctionNode} callback - The callback function to execute at each step.
- * @returns {void}
  */
 export const RaymarchingBox = ( steps, callback ) => {
 

src/materials/nodes/VolumeNodeMaterial.js

@@ -41,6 +41,15 @@ class VolumeNodeMaterial extends NodeMaterial {
 		 */
 		this.steps = 25;
 
+		/**
+		 * Offsets the distance a ray has been traveled through a volume.
+		 * Can be used to implement dithering to reduce banding.
+		 *
+		 * @type {Node<float>}
+		 * @default null
+		 */
+		this.offsetNode = null;
+
 		/**
 		 * Node used for scattering calculations.
 		 *

utils/docs/jsdoc.config.json

@@ -30,8 +30,10 @@
             "examples/jsm/math",
             "examples/jsm/modifiers",
             "examples/jsm/objects",
+            "examples/jsm/physics",
             "examples/jsm/renderers",
             "examples/jsm/textures",
+            "examples/jsm/transpiler",
             "examples/jsm/tsl",
             "examples/jsm/utils",
             "src"
@@ -45,6 +47,8 @@
             "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"
         ]
     }