Docs: More JSDoc. (#30675)

Author: Mugen87

examples/jsm/objects/GroundedSkybox.js

@@ -1,14 +1,32 @@
 import { Mesh, MeshBasicMaterial, SphereGeometry, Vector3 } from 'three';
 
 /**
- * A ground-projected skybox. The height is how far the camera that took the photo was above the ground -
- * a larger value will magnify the downward part of the image. By default the object is centered at the camera,
- * so it is often helpful to set skybox.position.y = height to put the ground at the origin. Set the radius
- * large enough to ensure your user's camera stays inside.
+ * A ground-projected skybox.
+ *
+ * By default the object is centered at the camera, so it is often helpful to set
+ * `skybox.position.y = height` to put the ground at the origin.
+ *
+ * ```js
+ * const height = 15, radius = 100;
+ *
+ * const skybox = new GroundedSkybox( envMap, height, radius );
+ * skybox.position.y = height;
+ * scene.add( skybox );
+ * ```
+ *
+ * @augments Mesh
  */
-
 class GroundedSkybox extends Mesh {
 
+	/**
+	 * Constructs a new ground-projected skybox.
+	 *
+	 * @param {Texture} map - The environment map to use.
+	 * @param {number} height - The height is how far the camera that took the photo was above the ground.
+	 * A larger value will magnify the downward part of the image.
+	 * @param {number} radius - The radius of the skybox. Must be large enough to ensure the scene's camera stays inside.
+	 * @param {number} [resolution=128] - The geometrix resolution of the skybox.
+	 */
 	constructor( map, height, radius, resolution = 128 ) {
 
 		if ( height <= 0 || radius <= 0 || resolution <= 0 ) {

examples/jsm/objects/Lensflare.js

@@ -15,16 +15,59 @@ import {
 	Vector4
 } from 'three';
 
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link LensflareMesh}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new Lensflare();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Lensflare extends Mesh {
 
+	/**
+	 * Constructs a new lensflare.
+	 */
 	constructor() {
 
 		super( Lensflare.Geometry, new MeshBasicMaterial( { opacity: 0, transparent: true } ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLensflare = true;
 
 		this.type = 'Lensflare';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -149,6 +192,11 @@ class Lensflare extends Mesh {
 
 		const mesh2 = new Mesh( geometry, material2 );
 
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -263,6 +311,10 @@ class Lensflare extends Mesh {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			material1a.dispose();
@@ -284,15 +336,52 @@ class Lensflare extends Mesh {
 
 }
 
-//
-
+/**
+ * Represents a single flare that can be added to a {@link Lensflare} container.
+ */
 class LensflareElement {
 
+	/**
+	 * Constructs a new lensflare element.
+	 *
+	 * @param {Texture} texture - The flare's texture.
+	 * @param {number} [size=1] - The size in pixels.
+	 * @param {number} [distance=0] - The normalized distance (`[0,1]`) from the light source.
+	 * A value of `0` means the flare is located at light source.
+	 * @param {Color} [color] - The flare's color
+	 */
 	constructor( texture, size = 1, distance = 0, color = new Color( 0xffffff ) ) {
 
+		/**
+		 * The flare's texture.
+		 *
+		 * @type {Texture}
+		 */
 		this.texture = texture;
+
+		/**
+		 * The size in pixels.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
+
+		/**
+		 * The normalized distance (`[0,1]`) from the light source.
+		 * A value of `0` means the flare is located at light source.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.distance = distance;
+
+		/**
+		 * The flare's color
+		 *
+		 * @type {Color}
+		 * @default (1,1,1)
+		 */
 		this.color = color;
 
 	}

examples/jsm/objects/LensflareMesh.js

@@ -18,16 +18,59 @@ import {
 
 import { texture, textureLoad, uv, ivec2, vec2, vec4, positionGeometry, reference, varyingProperty, materialReference, Fn } from 'three/tsl';
 
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Lensflare}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new LensflareMesh();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ */
 class LensflareMesh extends Mesh {
 
+	/**
+	 * Constructs a new lensflare mesh.
+	 */
 	constructor() {
 
 		super( LensflareMesh.Geometry, new MeshBasicNodeMaterial( { opacity: 0, transparent: true } ) );
 
-		this.isLensflare = true;
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isLensflareMesh = true;
 
 		this.type = 'LensflareMesh';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -146,7 +189,11 @@ class LensflareMesh extends Mesh {
 
 		} )();
 
-
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -264,6 +311,10 @@ class LensflareMesh extends Mesh {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			material1a.dispose();