Docs: More JSDoc. (#30610)

src/lights/AmbientLight.js

@@ -1,11 +1,36 @@
 import { Light } from './Light.js';
 
+/**
+ * This light globally illuminates all objects in the scene equally.
+ *
+ * It cannot be used to cast shadows as it does not have a direction.
+ *
+ * ```js
+ * const light = new THREE.AmbientLight( 0x404040 ); // soft white light
+ * scene.add( light );
+ * ```
+ *
+ * @augments Light
+ */
 class AmbientLight extends Light {
 
+	/**
+	 * Constructs a new ambient light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( color, intensity ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isAmbientLight = true;
 
 		this.type = 'AmbientLight';

src/lights/DirectionalLight.js

@@ -2,12 +2,52 @@ import { Light } from './Light.js';
 import { DirectionalLightShadow } from './DirectionalLightShadow.js';
 import { Object3D } from '../core/Object3D.js';
 
+/**
+ * A light that gets emitted in a specific direction. This light will behave
+ * as though it is infinitely far away and the rays produced from it are all
+ * parallel. The common use case for this is to simulate daylight; the sun is
+ * far enough away that its position can be considered to be infinite, and
+ * all light rays coming from it are parallel.
+ *
+ * A common point of confusion for directional lights is that setting the
+ * rotation has no effect. This is because three.js's DirectionalLight is the
+ * equivalent to what is often called a 'Target Direct Light' in other
+ * applications.
+ *
+ * This means that its direction is calculated as pointing from the light's
+ * {@link Object3D#position} to the {@link DirectionalLight#target} position
+ * (as opposed to a 'Free Direct Light' that just has a rotation
+ * component).
+ *
+ * This light can cast shadows - see the {@link DirectionalLightShadow} for details.
+ *
+ * ```js
+ * // White directional light at half intensity shining from the top.
+ * const directionalLight = new THREE.DirectionalLight( 0xffffff, 0.5 );
+ * scene.add( directionalLight );
+ * ```
+ *
+ * @augments Light
+ */
 class DirectionalLight extends Light {
 
+	/**
+	 * Constructs a new directional light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( color, intensity ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isDirectionalLight = true;
 
 		this.type = 'DirectionalLight';
@@ -15,8 +55,25 @@ class DirectionalLight extends Light {
 		this.position.copy( Object3D.DEFAULT_UP );
 		this.updateMatrix();
 
+		/**
+		 * The directional light points from its position to the
+		 * target's position.
+		 *
+		 * For the target's position to be changed to anything other
+		 * than the default, it must be added to the scene.
+		 *
+		 * It is also possible to set the target to be another 3D object
+		 * in the scene. The light will now track the target object.
+		 *
+		 * @type {Object3D}
+		 */
 		this.target = new Object3D();
 
+		/**
+		 * This property holds the light's shadow configuration.
+		 *
+		 * @type {DirectionalLightShadow}
+		 */
 		this.shadow = new DirectionalLightShadow();
 
 	}

src/lights/DirectionalLightShadow.js

@@ -1,12 +1,27 @@
 import { LightShadow } from './LightShadow.js';
 import { OrthographicCamera } from '../cameras/OrthographicCamera.js';
 
+/**
+ * Represents the shadow configuration of directional lights.
+ *
+ * @augments LightShadow
+ */
 class DirectionalLightShadow extends LightShadow {
 
+	/**
+	 * Constructs a new directional light shadow.
+	 */
 	constructor() {
 
 		super( new OrthographicCamera( - 5, 5, 5, - 5, 0.5, 500 ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isDirectionalLightShadow = true;
 
 	}

src/lights/HemisphereLight.js

@@ -2,12 +2,39 @@ import { Light } from './Light.js';
 import { Color } from '../math/Color.js';
 import { Object3D } from '../core/Object3D.js';
 
+/**
+ * A light source positioned directly above the scene, with color fading from
+ * the sky color to the ground color.
+ *
+ * This light cannot be used to cast shadows.
+ *
+ * ```js
+ * const light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
+ * scene.add( light );
+ * ```
+ *
+ * @augments Light
+ */
 class HemisphereLight extends Light {
 
+	/**
+	 * Constructs a new hemisphere light.
+	 *
+	 * @param {(number|Color|string)} [skyColor=0xffffff] - The light's sky color.
+	 * @param {(number|Color|string)} [groundColor=0xffffff] - The light's ground color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( skyColor, groundColor, intensity ) {
 
 		super( skyColor, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isHemisphereLight = true;
 
 		this.type = 'HemisphereLight';
@@ -15,6 +42,11 @@ class HemisphereLight extends Light {
 		this.position.copy( Object3D.DEFAULT_UP );
 		this.updateMatrix();
 
+		/**
+		 * The light's ground color.
+		 *
+		 * @type {Color}
+		 */
 		this.groundColor = new Color( groundColor );
 
 	}

src/lights/Light.js

@@ -1,21 +1,57 @@
 import { Object3D } from '../core/Object3D.js';
 import { Color } from '../math/Color.js';
 
+/**
+ * Abstract base class for lights - all other light types inherit the
+ * properties and methods described here.
+ *
+ * @abstract
+ * @augments Object3D
+ */
 class Light extends Object3D {
 
+	/**
+	 * Constructs a new light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( color, intensity = 1 ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLight = true;
 
 		this.type = 'Light';
 
+		/**
+		 * The light's color.
+		 *
+		 * @type {Color}
+		 */
 		this.color = new Color( color );
+
+		/**
+		 * The light's intensity.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.intensity = intensity;
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		// Empty here in base class; some subclasses override.

src/lights/LightProbe.js

@@ -1,14 +1,51 @@
 import { SphericalHarmonics3 } from '../math/SphericalHarmonics3.js';
 import { Light } from './Light.js';
 
+/**
+ * Light probes are an alternative way of adding light to a 3D scene. Unlike
+ * classical light sources (e.g. directional, point or spot lights), light
+ * probes do not emit light. Instead they store information about light
+ * passing through 3D space. During rendering, the light that hits a 3D
+ * object is approximated by using the data from the light probe.
+ *
+ * Light probes are usually created from (radiance) environment maps. The
+ * class {@link LightProbeGenerator} can be used to create light probes from
+ * cube textures or render targets. However, light estimation data could also
+ * be provided in other forms e.g. by WebXR. This enables the rendering of
+ * augmented reality content that reacts to real world lighting.
+ *
+ * The current probe implementation in three.js supports so-called diffuse
+ * light probes. This type of light probe is functionally equivalent to an
+ * irradiance environment map.
+ *
+ * @augments Light
+ */
 class LightProbe extends Light {
 
+	/**
+	 * Constructs a new light probe.
+	 *
+	 * @param {SphericalHarmonics3} sh - The spherical harmonics which represents encoded lighting information.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
 	constructor( sh = new SphericalHarmonics3(), intensity = 1 ) {
 
 		super( undefined, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLightProbe = true;
 
+		/**
+		 * A light probe uses spherical harmonics to encode lighting information.
+		 *
+		 * @type {SphericalHarmonics3}
+		 */
 		this.sh = sh;
 
 	}
@@ -23,6 +60,12 @@ class LightProbe extends Light {
 
 	}
 
+	/**
+	 * Deserializes the light prove from the given JSON.
+	 *
+	 * @param {Object} json - The JSON holding the serialized light probe.
+	 * @return {LightProbe} A reference to this light probe.
+	 */
 	fromJSON( json ) {
 
 		this.intensity = json.intensity; // TODO: Move this bit to Light.fromJSON();

src/lights/LightShadow.js

@@ -8,26 +8,137 @@ const _projScreenMatrix = /*@__PURE__*/ new Matrix4();
 const _lightPositionWorld = /*@__PURE__*/ new Vector3();
 const _lookTarget = /*@__PURE__*/ new Vector3();
 
+/**
+ * Abstract base class for light shadow classes. These classes
+ * represent the shadow configuration for different ligth types.
+ *
+ * @abstract
+ */
 class LightShadow {
 
+	/**
+	 * Constructs a new light shadow.
+	 *
+	 * @param {Camera} camera - The light's view of the world.
+	 */
 	constructor( camera ) {
 
+		/**
+		 * The light's view of the world.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 
+		/**
+		 * The intensity of the shadow. The default is `1`.
+		 * Valid values are in the range `[0, 1]`.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.intensity = 1;
 
+		/**
+		 * Shadow map bias, how much to add or subtract from the normalized depth
+		 * when deciding whether a surface is in shadow.
+		 *
+		 * The default is `0`. Very tiny adjustments here (in the order of `0.0001`)
+		 * may help reduce artifacts in shadows.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.bias = 0;
+
+		/**
+		 * Defines how much the position used to query the shadow map is offset along
+		 * the object normal. The default is `0`. Increasing this value can be used to
+		 * reduce shadow acne especially in large scenes where light shines onto
+		 * geometry at a shallow angle. The cost is that shadows may appear distorted.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.normalBias = 0;
+
+		/**
+		 * Setting this to values greater than 1 will blur the edges of the shadow.
+		 * High values will cause unwanted banding effects in the shadows - a greater
+		 * map size will allow for a higher value to be used here before these effects
+		 * become visible.
+		 *
+		 * The property has no effect when the shadow map type is `PCFSoftShadowMap` and
+		 * and it is recommended to increase softness by decreasing the shadow map size instead.
+		 *
+		 * The property has no effect when the shadow map type is `BasicShadowMap`.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.radius = 1;
+
+		/**
+		 * The amount of samples to use when blurring a VSM shadow map.
+		 *
+		 * @type {number}
+		 * @default 8
+		 */
 		this.blurSamples = 8;
 
+		/**
+		 * Defines the width and height of the shadow map. Higher values give better quality
+		 * shadows at the cost of computation time. Values must be powers of two.
+		 *
+		 * @type {Vector2}
+		 * @default (512,512)
+		 */
 		this.mapSize = new Vector2( 512, 512 );
 
+		/**
+		 * The depth map generated using the internal camera; a location beyond a
+		 * pixel's depth is in shadow. Computed internally during rendering.
+		 *
+		 * @type {?RenderTarget}
+		 * @default null
+		 */
 		this.map = null;
+
+		/**
+		 * The distribution map generated using the internal camera; an occlusion is
+		 * calculated based on the distribution of depths. Computed internally during
+		 * rendering.
+		 *
+		 * @type {?RenderTarget}
+		 * @default null
+		 */
 		this.mapPass = null;
+
+		/**
+		 * Model to shadow camera space, to compute location and depth in shadow map.
+		 * This is computed internally during rendering.
+		 *
+		 * @type {Matrix4}
+		 */
 		this.matrix = new Matrix4();
 
+		/**
+		 * Enables automatic updates of the light's shadow. If you do not require dynamic
+		 * lighting / shadows, you may set this to `false`.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.autoUpdate = true;
+
+		/**
+		 * When set to `true`, shadow maps will be updated in the next `render` call.
+		 * If you have set {@link LightShadow#autoUpdate} to `false`, you will need to
+		 * set this property to `true` and then make a render call to update the light's shadow.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsUpdate = false;
 
 		this._frustum = new Frustum();
@@ -43,18 +154,34 @@ class LightShadow {
 
 	}
 
+	/**
+	 * Used internally by the renderer to get the number of viewports that need
+	 * to be rendered for this shadow.
+	 *
+	 * @return {number} The viewport count.
+	 */
 	getViewportCount() {
 
 		return this._viewportCount;
 
 	}
 
+	/**
+	 * Gets the shadow cameras frustum. Used internally by the renderer to cull objects.
+	 *
+	 * @return {Frustum} The shadow camera frustum.
+	 */
 	getFrustum() {
 
 		return this._frustum;
 
 	}
 
+	/**
+	 * Update the matrices for the camera and shadow, used internally by the renderer.
+	 *
+	 * @param {Light} light - The light for which the shadow is being rendered.
+	 */
 	updateMatrices( light ) {
 
 		const shadowCamera = this.camera;
@@ -81,18 +208,33 @@ class LightShadow {
 
 	}
 
+	/**
+	 * Returns a viewport definition for the given viewport index.
+	 *
+	 * @param {number} viewportIndex - The viewport index.
+	 * @return {Vector4} The viewport.
+	 */
 	getViewport( viewportIndex ) {
 
 		return this._viewports[ viewportIndex ];
 
 	}
 
+	/**
+	 * Returns the frame extends.
+	 *
+	 * @return {Vector2} The frame extends.
+	 */
 	getFrameExtents() {
 
 		return this._frameExtents;
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		if ( this.map ) {
@@ -109,6 +251,12 @@ class LightShadow {
 
 	}
 
+	/**
+	 * Copies the values of the given light shadow instance to this instance.
+	 *
+	 * @param {LightShadow} source - The light shadow to copy.
+	 * @return {LightShadow} A reference to this light shadow instance.
+	 */
 	copy( source ) {
 
 		this.camera = source.camera.clone();
@@ -124,12 +272,23 @@ class LightShadow {
 
 	}
 
+	/**
+	 * Returns a new light shadow instance with copied values from this instance.
+	 *
+	 * @return {LightShadow} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Serializes the light shadow into JSON.
+	 *
+	 * @return {Object} A JSON object representing the serialized light shadow.
+	 * @see {@link ObjectLoader#parse}
+	 */
 	toJSON() {
 
 		const object = {};

src/lights/PointLight.js

@@ -1,23 +1,82 @@
 import { Light } from './Light.js';
 import { PointLightShadow } from './PointLightShadow.js';
 
+/**
+ * A light that gets emitted from a single point in all directions. A common
+ * use case for this is to replicate the light emitted from a bare
+ * lightbulb.
+ *
+ * This light can cast shadows - see the {@link PointLightShadow} for details.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xff0000, 1, 100 );
+ * light.position.set( 50, 50, 50 );
+ * scene.add( light );
+ * ```
+ *
+ * @augments Light
+ */
 class PointLight extends Light {
 
+	/**
+	 * Constructs a new point light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity measured in candela (cd).
+	 * @param {number} [distance=0] - Maximum range of the light. `0` means no limit.
+	 * @param {number} [decay=2] - The amount the light dims along the distance of the light.
+	 */
 	constructor( color, intensity, distance = 0, decay = 2 ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isPointLight = true;
 
 		this.type = 'PointLight';
 
+		/**
+		 * When distance is zero, light will attenuate according to inverse-square
+		 * law to infinite distance. When distance is non-zero, light will attenuate
+		 * according to inverse-square law until near the distance cutoff, where it
+		 * will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not
+		 * physically correct.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.distance = distance;
+
+		/**
+		 * The amount the light dims along the distance of the light. In context of
+		 * physically-correct rendering the default value should not be changed.
+		 *
+		 * @type {number}
+		 * @default 2
+		 */
 		this.decay = decay;
 
+		/**
+		 * This property holds the light's shadow configuration.
+		 *
+		 * @type {PointLightShadow}
+		 */
 		this.shadow = new PointLightShadow();
 
 	}
 
+	/**
+	 * The light's power. Power is the luminous power of the light measured in lumens (lm).
+	 * Changing the power will also change the light's intensity.
+	 *
+	 * @type {number}
+	 */
 	get power() {
 
 		// compute the light's luminous power (in lumens) from its intensity (in candela)

src/lights/PointLightShadow.js

@@ -9,12 +9,27 @@ const _projScreenMatrix = /*@__PURE__*/ new Matrix4();
 const _lightPositionWorld = /*@__PURE__*/ new Vector3();
 const _lookTarget = /*@__PURE__*/ new Vector3();
 
+/**
+ * Represents the shadow configuration of point lights.
+ *
+ * @augments LightShadow
+ */
 class PointLightShadow extends LightShadow {
 
+	/**
+	 * Constructs a new point light shadow.
+	 */
 	constructor() {
 
 		super( new PerspectiveCamera( 90, 1, 0.5, 500 ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isPointLightShadow = true;
 
 		this._frameExtents = new Vector2( 4, 2 );
@@ -61,6 +76,12 @@ class PointLightShadow extends LightShadow {
 
 	}
 
+	/**
+	 * Update the matrices for the camera and shadow, used internally by the renderer.
+	 *
+	 * @param {Light} light - The light for which the shadow is being rendered.
+	 * @param {number} [viewportIndex=0] - The viewport index.
+	 */
 	updateMatrices( light, viewportIndex = 0 ) {
 
 		const camera = this.camera;

src/lights/RectAreaLight.js

@@ -1,20 +1,79 @@
 import { Light } from './Light.js';
 
+/**
+ * This class emits light uniformly across the face a rectangular plane.
+ * This light type can be used to simulate light sources such as bright
+ * windows or strip lighting.
+ *
+ * Important Notes:
+ *
+ * - There is no shadow support.
+ * - Only PBR materials are supported.
+ * - You have to include `RectAreaLightUniformsLib` (`WebGLRenderer`) or `RectAreaLightTexturesLib` (`WebGPURenderer`)
+ * into your app and init the uniforms/textures.
+ *
+ * ```js
+ * RectAreaLightUniformsLib.init(); // only relevant for WebGLRenderer
+ * THREE.RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() ); //  only relevant for WebGPURenderer
+ *
+ * const intensity = 1; const width = 10; const height = 10;
+ * const rectLight = new THREE.RectAreaLight( 0xffffff, intensity, width, height );
+ * rectLight.position.set( 5, 5, 0 );
+ * rectLight.lookAt( 0, 0, 0 );
+ * scene.add( rectLight )
+ * ```
+ *
+ * @augments Light
+ */
 class RectAreaLight extends Light {
 
+	/**
+	 * Constructs a new area light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 * @param {number} [width=10] - The width of the light.
+	 * @param {number} [height=10] - The height of the light.
+	 */
 	constructor( color, intensity, width = 10, height = 10 ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRectAreaLight = true;
 
 		this.type = 'RectAreaLight';
 
+		/**
+		 * The width of the light.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.width = width;
+
+		/**
+		 * The height of the light.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.height = height;
 
 	}
 
+	/**
+	 * The light's power. Power is the luminous power of the light measured in lumens (lm).
+	 * Changing the power will also change the light's intensity.
+	 *
+	 * @type {number}
+	 */
 	get power() {
 
 		// compute the light's luminous power (in lumens) from its intensity (in nits)

src/lights/SpotLight.js

@@ -2,12 +2,51 @@ import { Light } from './Light.js';
 import { SpotLightShadow } from './SpotLightShadow.js';
 import { Object3D } from '../core/Object3D.js';
 
+/**
+ * This light gets emitted from a single point in one direction, along a cone
+ * that increases in size the further from the light it gets.
+ *
+ * This light can cast shadows - see the {@link SpotLightShadow} for details.
+ *
+ * ```js
+ * // white spotlight shining from the side, modulated by a texture
+ * const spotLight = new THREE.SpotLight( 0xffffff );
+ * spotLight.position.set( 100, 1000, 100 );
+ * spotLight.map = new THREE.TextureLoader().load( url );
+ *
+ * spotLight.castShadow = true;
+ * spotLight.shadow.mapSize.width = 1024;
+ * spotLight.shadow.mapSize.height = 1024;
+ * spotLight.shadow.camera.near = 500;
+ * spotLight.shadow.camera.far = 4000;
+ * spotLight.shadow.camera.fov = 30;s
+ * ```
+ *
+ * @augments Light
+ */
 class SpotLight extends Light {
 
+	/**
+	 * Constructs a new spot light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity measured in candela (cd).
+	 * @param {number} [distance=0] - Maximum range of the light. `0` means no limit.
+	 * @param {number} [angle=Math.PI/3] - Maximum angle of light dispersion from its direction whose upper bound is `Math.PI/2`.
+	 * @param {number} [penumbra=0] - Percent of the spotlight cone that is attenuated due to penumbra. Value range is `[0,1]`.
+	 * @param {number} [decay=2] - The amount the light dims along the distance of the light.
+	 */
 	constructor( color, intensity, distance = 0, angle = Math.PI / 3, penumbra = 0, decay = 2 ) {
 
 		super( color, intensity );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSpotLight = true;
 
 		this.type = 'SpotLight';
@@ -15,19 +54,82 @@ class SpotLight extends Light {
 		this.position.copy( Object3D.DEFAULT_UP );
 		this.updateMatrix();
 
+		/**
+		 * The spot light points from its position to the
+		 * target's position.
+		 *
+		 * For the target's position to be changed to anything other
+		 * than the default, it must be added to the scene.
+		 *
+		 * It is also possible to set the target to be another 3D object
+		 * in the scene. The light will now track the target object.
+		 *
+		 * @type {Object3D}
+		 */
 		this.target = new Object3D();
 
+		/**
+		 * Maximum range of the light. `0` means no limit.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.distance = distance;
+
+		/**
+		 * Maximum angle of light dispersion from its direction whose upper bound is `Math.PI/2`.
+		 *
+		 * @type {number}
+		 * @default Math.PI/3
+		 */
 		this.angle = angle;
+
+		/**
+		 * Percent of the spotlight cone that is attenuated due to penumbra.
+		 * Value range is `[0,1]`.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.penumbra = penumbra;
+
+		/**
+		 * The amount the light dims along the distance of the light. In context of
+		 * physically-correct rendering the default value should not be changed.
+		 *
+		 * @type {number}
+		 * @default 2
+		 */
 		this.decay = decay;
 
+		/**
+		 * A texture used to modulate the color of the light. The spot light
+		 * color is mixed with the RGB value of this texture, with a ratio
+		 * corresponding to its alpha value. The cookie-like masking effect is
+		 * reproduced using pixel values (0, 0, 0, 1-cookie_value).
+		 *
+		 * *Warning*: This property is disabled if {@link Object3D#castShadow} is set to `false`.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.map = null;
 
+		/**
+		 * This property holds the light's shadow configuration.
+		 *
+		 * @type {SpotLightShadow}
+		 */
 		this.shadow = new SpotLightShadow();
 
 	}
 
+	/**
+	 * The light's power. Power is the luminous power of the light measured in lumens (lm).
+	 *  Changing the power will also change the light's intensity.
+	 *
+	 * @type {number}
+	 */
 	get power() {
 
 		// compute the light's luminous power (in lumens) from its intensity (in candela)

src/lights/SpotLightShadow.js

@@ -2,14 +2,36 @@ import { LightShadow } from './LightShadow.js';
 import { RAD2DEG } from '../math/MathUtils.js';
 import { PerspectiveCamera } from '../cameras/PerspectiveCamera.js';
 
+/**
+ * Represents the shadow configuration of directional lights.
+ *
+ * @augments LightShadow
+ */
 class SpotLightShadow extends LightShadow {
 
+	/**
+	 * Constructs a new spot light shadow.
+	 */
 	constructor() {
 
 		super( new PerspectiveCamera( 50, 1, 0.5, 500 ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSpotLightShadow = true;
 
+		/**
+		 * Used to focus the shadow camera. The camera's field of view is set as a
+		 * percentage of the spotlight's field-of-view. Range is `[0, 1]`.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.focus = 1;
 
 	}

src/lights/webgpu/IESSpotLight.js

@@ -1,11 +1,32 @@
 import { SpotLight } from '../SpotLight.js';
 
+/**
+ * A IES version of {@link SpotLight}. Can only be used with {@link WebGPURenderer}.
+ *
+ * @augments SpotLight
+ */
 class IESSpotLight extends SpotLight {
 
+	/**
+	 * Constructs a new IES spot light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity measured in candela (cd).
+	 * @param {number} [distance=0] - Maximum range of the light. `0` means no limit.
+	 * @param {number} [angle=Math.PI/3] - Maximum angle of light dispersion from its direction whose upper bound is `Math.PI/2`.
+	 * @param {number} [penumbra=0] - Percent of the spotlight cone that is attenuated due to penumbra. Value range is `[0,1]`.
+	 * @param {number} [decay=2] - The amount the light dims along the distance of the light.
+	 */
 	constructor( color, intensity, distance, angle, penumbra, decay ) {
 
 		super( color, intensity, distance, angle, penumbra, decay );
 
+		/**
+		 * TOOD
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.iesMap = null;
 
 	}

utils/docs/jsdoc.config.json

@@ -19,6 +19,7 @@
             "src/core/EventDispatcher.js",
             "src/extras",
             "src/helpers",
+            "src/lights",
             "src/loaders/nodes", 
             "src/loaders/Loader.js", 
             "src/materials/nodes",