Docs: Add more JSDoc. (#30641)

examples/jsm/animation/AnimationClipCreator.js

@@ -7,8 +7,21 @@ import {
 	VectorKeyframeTrack
 } from 'three';
 
+/**
+ * A utility class with factory methods for creating basic animation clips.
+ *
+ * @hideconstructor
+ */
 class AnimationClipCreator {
 
+	/**
+	 * Creates an animation clip that rotates a 3D object 360 degress
+	 * in the given period of time around the given axis.
+	 *
+	 * @param {number} period - The duration of the animation.
+	 * @param {('x'|'y'|'z')} [axis='x'] - The axis of rotation.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateRotationAnimation( period, axis = 'x' ) {
 
 		const times = [ 0, period ], values = [ 0, 360 ];
@@ -21,6 +34,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that scales a 3D object from `0` to `1`
+	 * in the given period of time along the given axis.
+	 *
+	 * @param {number} period - The duration of the animation.
+	 * @param {('x'|'y'|'z')} [axis='x'] - The axis to scale the 3D object along.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateScaleAxisAnimation( period, axis = 'x' ) {
 
 		const times = [ 0, period ], values = [ 0, 1 ];
@@ -33,6 +54,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that translates a 3D object in a shake pattern
+	 * in the given period.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {number} shakeScale - The scale of the shake.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateShakeAnimation( duration, shakeScale ) {
 
 		const times = [], values = [], tmp = new Vector3();
@@ -55,6 +84,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that scales a 3D object in a pulse pattern
+	 * in the given period.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {number} pulseScale - The scale of the pulse.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreatePulsationAnimation( duration, pulseScale ) {
 
 		const times = [], values = [], tmp = new Vector3();
@@ -77,6 +114,12 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that toggles the visbility of a 3D object.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateVisibilityAnimation( duration ) {
 
 		const times = [ 0, duration / 2, duration ], values = [ true, false, true ];
@@ -89,6 +132,14 @@ class AnimationClipCreator {
 
 	}
 
+	/**
+	 * Creates an animation clip that animates the `color` property of a 3D object's
+	 * material.
+	 *
+	 * @param {number} duration - The duration of the animation.
+	 * @param {Array<Color>} colors - An array of colors that should be sequentially animated.
+	 * @return {AnimationClip} The created animation clip.
+	 */
 	static CreateMaterialColorAnimation( duration, colors ) {
 
 		const times = [], values = [],

examples/jsm/animation/CCDIKSolver.js

@@ -25,36 +25,31 @@ const _axis = new Vector3();
 const _vector = new Vector3();
 const _matrix = new Matrix4();
 
-
 /**
- * CCD Algorithm
- *  - https://web.archive.org/web/20221206080850/https://sites.google.com/site/auraliusproject/ccd-algorithm
+ * This class solves the Inverse Kinematics Problem with a [CCD Algorithm]{@link https://web.archive.org/web/20221206080850/https://sites.google.com/site/auraliusproject/ccd-algorithm}.
  *
- * // ik parameter example
- * //
- * // target, effector, index in links are bone index in skeleton.bones.
- * // the bones relation should be
- * // <-- parent                                  child -->
- * // links[ n ], links[ n - 1 ], ..., links[ 0 ], effector
- * iks = [ {
- *	target: 1,
- *	effector: 2,
- *	links: [ { index: 5, limitation: new Vector3( 1, 0, 0 ) }, { index: 4, enabled: false }, { index : 3 } ],
- *	iteration: 10,
- *	minAngle: 0.0,
- *	maxAngle: 1.0,
- * } ];
+ * `CCDIKSolver` is designed to work with instances of {@link SkinnedMesh}.
  */
-
 class CCDIKSolver {
 
 	/**
-	 * @param {THREE.SkinnedMesh} mesh
-	 * @param {Array<Object>} iks
+	 * @param {SkinnedMesh} mesh - The skinned mesh.
+	 * @param {Array<CCDIKSolver~IK>} [iks=[]] - The IK objects.
 	 */
 	constructor( mesh, iks = [] ) {
 
+		/**
+		 * The skinned mesh.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.mesh = mesh;
+
+		/**
+		 * The IK objects.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.iks = iks;
 
 		this._initialQuaternions = [];
@@ -78,10 +73,10 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update all IK bones.
+	 * Updates all IK bones by solving the CCD algorithm.
 	 *
 	 * @param {number} [globalBlendFactor=1.0] - Blend factor applied if an IK chain doesn't have its own .blendFactor.
-	 * @return {CCDIKSolver}
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
 	update( globalBlendFactor = 1.0 ) {
 
@@ -98,11 +93,11 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Update one IK bone
+	 * Updates one IK bone solving the CCD algorithm.
 	 *
-	 * @param {Object} ik parameter
-	 * @param {number} [overrideBlend=1.0] - If the ik object does not define .blendFactor, this value is used.
-	 * @return {CCDIKSolver}
+	 * @param {CCDIKSolver~IK} ik - The IK to update.
+	 * @param {number} [overrideBlend=1.0] - If the IK object does not define `blendFactor`, this value is used.
+	 * @return {CCDIKSolver} A reference to this instance.
 	 */
 	updateOne( ik, overrideBlend = 1.0 ) {
 
@@ -258,10 +253,10 @@ class CCDIKSolver {
 	}
 
 	/**
-	 * Creates Helper
+	 * Creates a helper for visualizing tehh CCDIK.
 	 *
-	 * @param {number} sphereSize
-	 * @return {CCDIKHelper}
+	 * @param {number} sphereSize - The sphere size.
+	 * @return {CCDIKHelper} The created helper.
 	 */
 	createHelper( sphereSize ) {
 
@@ -324,27 +319,50 @@ function setPositionOfBoneToAttributeArray( array, index, bone, matrixWorldInv )
 }
 
 /**
- * Visualize IK bones
+ * Helper for visualizing IK bones.
+ *
+ * @augments Object3D
  */
 class CCDIKHelper extends Object3D {
 
 	/**
-	 * @param {SkinnedMesh} mesh
- 	 * @param {Array<Object>} [iks=[]]
- 	 * @param {number} [sphereSize=0.25]
+	 * @param {SkinnedMesh} mesh - The skinned mesh.
+ 	 * @param {Array<CCDIKSolver~IK>} [iks=[]] - The IK objects.
+ 	 * @param {number} [sphereSize=0.25] - The sphere size.
 	 */
 	constructor( mesh, iks = [], sphereSize = 0.25 ) {
 
 		super();
 
+		/**
+		 * The skinned mesh this helper refers to.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.root = mesh;
+
+		/**
+		 * The IK objects.
+		 *
+		 * @type {Array<CCDIKSolver~IK>}
+		 */
 		this.iks = iks;
 
 		this.matrix.copy( mesh.matrixWorld );
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * The helpers sphere geometry.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.sphereGeometry = new SphereGeometry( sphereSize, 16, 8 );
 
+		/**
+		 * The material for the target spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.targetSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0xff8888 ),
 			depthTest: false,
@@ -352,6 +370,11 @@ class CCDIKHelper extends Object3D {
 			transparent: true
 		} );
 
+		/**
+		 * The material for the effector spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.effectorSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0x88ff88 ),
 			depthTest: false,
@@ -359,6 +382,11 @@ class CCDIKHelper extends Object3D {
 			transparent: true
 		} );
 
+		/**
+		 * The material for the link spheres.
+		 *
+		 * @type {MeshBasicMaterial}
+		 */
 		this.linkSphereMaterial = new MeshBasicMaterial( {
 			color: new Color( 0x8888ff ),
 			depthTest: false,
@@ -366,6 +394,11 @@ class CCDIKHelper extends Object3D {
 			transparent: true
 		} );
 
+		/**
+		 * A global line matreial.
+		 *
+		 * @type {LineBasicMaterial}
+		 */
 		this.lineMaterial = new LineBasicMaterial( {
 			color: new Color( 0xff0000 ),
 			depthTest: false,
@@ -377,11 +410,6 @@ class CCDIKHelper extends Object3D {
 
 	}
 
-	/**
-	 * Updates IK bones visualization.
-	 *
-	 * @param {boolean} force
-	 */
 	updateMatrixWorld( force ) {
 
 		const mesh = this.root;
@@ -446,7 +474,8 @@ class CCDIKHelper extends Object3D {
 	}
 
 	/**
-	 * Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
+	 * Frees the GPU-related resources allocated by this instance.
+	 * Call this method whenever this instance is no longer used in your app.
 	 */
 	dispose() {
 
@@ -531,4 +560,29 @@ class CCDIKHelper extends Object3D {
 
 }
 
+/**
+ * This type represents IK configuration objects.
+ *
+ * @typedef {Object} CCDIKSolver~IK
+ * @property {number} target - The target bone index which refers to a bone in the `Skeleton.bones` array.
+ * @property {number} effector - The effector bone index which refers to a bone in the `Skeleton.bones` array.
+ * @property {Array<CCDIKSolver~BoneLink>} links - An array of bone links.
+ * @property {number} [iteration=1] - Iteration number of calculation. Smaller is faster but less precise.
+ * @property {number} [minAngle] - Minimum rotation angle in a step in radians.
+ * @property {number} [maxAngle] - Minimum rotation angle in a step in radians.
+ * @property {number} [blendFactor] - The blend factor.
+ **/
+
+/**
+ * This type represents bone links.
+ *
+ * @typedef {Object} CCDIKSolver~BoneLink
+ * @property {number} index - The index of a linked bone which refers to a bone in the `Skeleton.bones` array.
+ * @property {number} [limitation] - Rotation axis.
+ * @property {number} [rotationMin] - Rotation minimum limit.
+ * @property {number} [rotationMax] - Rotation maximum limit.
+ * @property {boolean} [enabled=true] - Whether the link is enabled or not.
+ **/
+
+
 export { CCDIKSolver, CCDIKHelper };

examples/jsm/capabilities/WebGL.js

@@ -1,5 +1,15 @@
+/**
+ * A utility module with basic WebGL 2 capability testing.
+ *
+ * @hideconstructor
+ */
 class WebGL {
 
+	/**
+	 * Returns `true` if WebGL 2 is available.
+	 *
+	 * @return {boolean} Whether WebGL 2 is available or not.
+	 */
 	static isWebGL2Available() {
 
 		try {
@@ -15,6 +25,13 @@ class WebGL {
 
 	}
 
+	/**
+	 * Returns `true` if the given color space is available. This method can only be used
+	 * if WebGL 2 is supported.
+	 *
+	 * @param {string} colorSpace - The color space to test.
+	 * @return {boolean} Whether the given color space is available or not.
+	 */
 	static isColorSpaceAvailable( colorSpace ) {
 
 		try {
@@ -32,13 +49,21 @@ class WebGL {
 
 	}
 
+	/**
+	 * Returns a `div` element representing a formatted error message that can be appended in
+	 * web sites if WebGL 2 isn't supported.
+	 *
+	 * @return {HTMLDivElement} A `div` element representing a formatted error message that WebGL 2 isn't supported.
+	 */
 	static getWebGL2ErrorMessage() {
 
-		return this.getErrorMessage( 2 );
+		return this._getErrorMessage( 2 );
 
 	}
 
-	static getErrorMessage( version ) {
+	// private
+
+	static _getErrorMessage( version ) {
 
 		const names = {
 			1: 'WebGL',
@@ -105,7 +130,7 @@ class WebGL {
 
 		console.warn( 'getWebGLErrorMessage() has been deprecated and will be removed in r178. Use getWebGL2ErrorMessage() instead.' );
 
-		return this.getErrorMessage( 1 );
+		return this._getErrorMessage( 1 );
 
 	}
 

examples/jsm/capabilities/WebGPU.js

@@ -6,20 +6,30 @@ if ( typeof window !== 'undefined' && isAvailable ) {
 
 }
 
+/**
+ * A utility module with basic WebGPU capability testing.
+ *
+ * @hideconstructor
+ */
 class WebGPU {
 
+	/**
+	 * Returns `true` if WebGPU is available.
+	 *
+	 * @return {boolean} Whether WebGPU is available or not.
+	 */
 	static isAvailable() {
 
 		return Boolean( isAvailable );
 
 	}
 
-	static getStaticAdapter() {
-
-		return isAvailable;
-
-	}
-
+	/**
+	 * Returns a `div` element representing a formatted error message that can be appended in
+	 * web sites if WebGPU isn't supported.
+	 *
+	 * @return {HTMLDivElement} A `div` element representing a formatted error message that WebGPU isn't supported.
+	 */
 	static getErrorMessage() {
 
 		const message = 'Your browser does not support <a href="https://gpuweb.github.io/gpuweb/" style="color:blue">WebGPU</a> yet';

examples/jsm/controls/ArcballControls.js

@@ -59,9 +59,28 @@ const _transformation = {
 
 };
 
-//events
+/**
+ * Fires when the camera has been transformed by the controls.
+ *
+ * @event ArcballControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires when an interaction was initiated.
+ *
+ * @event ArcballControls#start
+ * @type {Object}
+ */
 const _startEvent = { type: 'start' };
+
+/**
+ * Fires when an interaction has finished.
+ *
+ * @event ArcballControls#end
+ * @type {Object}
+ */
 const _endEvent = { type: 'end' };
 
 const _raycaster = new Raycaster();
@@ -73,24 +92,65 @@ const _scalePointTemp = new Vector3();
 
 const _EPS = 0.000001;
 
-
+/**
+ * Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced navigation functionality.
+ * Cursor/finger positions and movements are mapped over a virtual trackball surface represented by a gizmo and mapped in intuitive and
+ * consistent camera movements. Dragging cursor/fingers will cause camera to orbit around the center of the trackball in a conservative
+ * way (returning to the starting point will make the camera to return to its starting orientation).
+ *
+ * In addition to supporting pan, zoom and pinch gestures, Arcball controls provide focus< functionality with a double click/tap for intuitively
+ * moving the object's point of interest in the center of the virtual trackball. Focus allows a much better inspection and navigation in complex
+ * environment. Moreover Arcball controls allow FOV manipulation (in a vertigo-style method) and z-rotation. Saving and restoring of Camera State
+ * is supported also through clipboard (use ctrl+c and ctrl+v shortcuts for copy and paste the state).
+ *
+ * Unlike {@link OrbitControls} and {@link TrackballControls}, `ArcballControls` doesn't require `update()` to be called externally in an
+ * animation loop when animations are on.
+ *
+ * @augments Controls
+ */
 class ArcballControls extends Controls {
 
 	/**
+	 * Constructs a new controls instance.
 	 *
-	 * @param {Camera} camera Virtual camera used in the scene
-	 * @param {?HTMLElement} [domElement=null] Renderer's dom element
-	 * @param {?Scene} [scene=null] The scene to be rendered
+	 * @param {Camera} camera - The camera to be controlled. The camera must not be a child of another object, unless that object is the scene itself.
+	 * @param {?HTMLDOMElement} [domElement=null] - The HTML element used for event listeners.
+	 * @param {?Scene} [scene=null] The scene rendered by the camera. If not given, gizmos cannot be shown.
 	 */
 	constructor( camera, domElement = null, scene = null ) {
 
 		super( camera, domElement );
 
+		/**
+		 * The scene rendered by the camera. If not given, gizmos cannot be shown.
+		 *
+		 * @type {?Scene}
+		 * @default null
+		 */
 		this.scene = scene;
+
+		/**
+		 * The control's focus point.
+		 *
+		 * @type {Vector3}
+		 */
 		this.target = new Vector3();
 		this._currentTarget = new Vector3();
+
+		/**
+		 * The size of the gizmo relative to the screen width and height.
+		 *
+		 * @type {number}
+		 * @default 0.67
+		 */
 		this.radiusFactor = 0.67;
 
+		/**
+		 * Holds the mouse actions of this controls. This property is maintained by the methods
+		 * `setMouseAction()` and `unsetMouseAction()`.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.mouseActions = [];
 		this._mouseOp = null;
 
@@ -178,8 +238,13 @@ class ArcballControls extends Controls {
 		this._timeStart = - 1; //initial time
 		this._animationId = - 1;
 
-		//focus animation
-		this.focusAnimationTime = 500; //duration of focus animation in ms
+		/**
+		 * Duration of focus animations in ms.
+		 *
+		 * @type {number}
+		 * @default 500
+		 */
+		this.focusAnimationTime = 500;
 
 		//rotate animation
 		this._timePrev = 0; //time at which previous rotate operation has been detected
@@ -191,28 +256,161 @@ class ArcballControls extends Controls {
 		this._wPrev = 0; //angular velocity of the previous rotate operation
 		this._wCurr = 0; //angular velocity of the current rotate operation
 
-
 		//parameters
+
+		/**
+		 * If set to `true`, the camera's near and far values will be adjusted every time zoom is
+		 * performed trying to maintain the same visible portion given by initial near and far
+		 * values. Only works with perspective cameras.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.adjustNearFar = false;
-		this.scaleFactor = 1.1;	//zoom/distance multiplier
+
+		/**
+		 * The scaling factor used when performing zoom operation.
+		 *
+		 * @type {number}
+		 * @default 1.1
+		 */
+		this.scaleFactor = 1.1;
+
+		/**
+		 * The damping inertia used if 'enableAnimations` is set to `true`.
+		 *
+		 * @type {number}
+		 * @default 25
+		 */
 		this.dampingFactor = 25;
-		this.wMax = 20;	//maximum angular velocity allowed
-		this.enableAnimations = true; //if animations should be performed
-		this.enableGrid = false; //if grid should be showed during pan operation
-		this.cursorZoom = false;	//if wheel zoom should be cursor centered
+
+		/**
+		 * Maximum angular velocity allowed on rotation animation start.
+		 *
+		 * @type {number}
+		 * @default 20
+		 */
+		this.wMax = 20;
+
+		/**
+		 * Set to `true` to enable animations for rotation (damping) and focus operation.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.enableAnimations = true;
+
+		/**
+		 * If set to `true`, a grid will appear when panning operation is being performed
+		 * (desktop interaction only).
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.enableGrid = false;
+
+		/**
+		 * Set to `true` to make zoom become cursor centered.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.cursorZoom = false;
+
+		/**
+		 * The minimum FOV in degrees.
+		 *
+		 * @type {number}
+		 * @default 5
+		 */
 		this.minFov = 5;
+
+		/**
+		 * The maximum FOV in degrees.
+		 *
+		 * @type {number}
+		 * @default 90
+		 */
 		this.maxFov = 90;
+
+		/**
+		 * Speed of rotation.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.rotateSpeed = 1;
 
+		/**
+		 * Enable or disable camera panning.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enablePan = true;
+
+		/**
+		 * Enable or disable camera rotation.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enableRotate = true;
+
+		/**
+		 * Enable or disable camera zoom.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enableZoom = true;
+
+		/**
+		 * Enable or disable gizmos.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enableGizmos = true;
+
+		/**
+		 * Enable or disable camera focusing on double-tap (or click) operations.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enableFocus = true;
 
+		/**
+		 * How far you can dolly in. For perspective cameras only.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minDistance = 0;
+
+		/**
+		 * How far you can dolly out. For perspective cameras only.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxDistance = Infinity;
+
+		/**
+		 * How far you can zoom in. For orthographic cameras only.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minZoom = 0;
+
+		/**
+		 * How far you can zoom out. For orthographic cameras only.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxZoom = Infinity;
 
 		//trackball parameters
@@ -1044,9 +1242,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set _center's x/y coordinates
-	 * @param {number} clientX
-	 * @param {number} clientY
+	 * Set _center's x/y coordinates.
+	 *
+	 * @private
+	 * @param {number} clientX - The x coordinate.
+	 * @param {number} clientY - The y coordinate.
 	 */
 	setCenter( clientX, clientY ) {
 
@@ -1056,7 +1256,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set default mouse actions
+	 * Set default mouse actions.
+	 *
+	 * @private
 	 */
 	initializeMouseActions() {
 
@@ -1075,10 +1277,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Compare two mouse actions
-	 * @param {Object} action1
-	 * @param {Object} action2
-	 * @returns {boolean} True if action1 and action 2 are the same mouse action, false otherwise
+	 * Compare two mouse actions.
+	 *
+	 * @private
+	 * @param {Object} action1 - The first mouse action.
+	 * @param {Object} action2 - The second mouse action.
+	 * @returns {boolean} `true` if action1 and action 2 are the same mouse action, `false` otherwise.
 	 */
 	compareMouseAction( action1, action2 ) {
 
@@ -1103,11 +1307,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set a new mouse action by specifying the operation to be performed and a mouse/key combination. In case of conflict, replaces the existing one
-	 * @param {'PAN'|'ROTATE'|'ZOOM'|'FOV'} operation The operation to be performed ('PAN', 'ROTATE', 'ZOOM', 'FOV')
-	 * @param {0|1|2|'WHEEL'} mouse A mouse button (0, 1, 2) or 'WHEEL' for wheel notches
-	 * @param {'CTRL'|'SHIFT'|null} [key=null] The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed
-	 * @returns {boolean} True if the mouse action has been successfully added, false otherwise
+	 * Set a new mouse action by specifying the operation to be performed and a mouse/key combination. In case of conflict, replaces the existing one.
+	 *
+	 * @param {'PAN'|'ROTATE'|'ZOOM'|'FOV'} operation - The operation to be performed ('PAN', 'ROTATE', 'ZOOM', 'FOV').
+	 * @param {0|1|2|'WHEEL'} mouse - A mouse button (0, 1, 2) or 'WHEEL' for wheel notches.
+	 * @param {'CTRL'|'SHIFT'|null} [key=null] - The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed.
+	 * @returns {boolean} `true` if the mouse action has been successfully added, `false` otherwise.
 	 */
 	setMouseAction( operation, mouse, key = null ) {
 
@@ -1184,10 +1389,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Remove a mouse action by specifying its mouse/key combination
-	 * @param {0|1|2|'WHEEL'} mouse A mouse button (0, 1, 2) or 'WHEEL' for wheel notches
-	 * @param {'CTRL'|'SHIFT'|null} key The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed
-	 * @returns {boolean} True if the operation has been successfully removed, false otherwise
+	 * Remove a mouse action by specifying its mouse/key combination.
+	 *
+	 * @param {0|1|2|'WHEEL'} mouse - A mouse button (0, 1, 2) or 'WHEEL' for wheel notches.
+	 * @param {'CTRL'|'SHIFT'|null} key - The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed.
+	 * @returns {boolean} `true` if the operation has been successfully removed, `false` otherwise.
 	 */
 	unsetMouseAction( mouse, key = null ) {
 
@@ -1207,10 +1413,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Return the operation associated to a mouse/keyboard combination
-	 * @param {0|1|2|'WHEEL'} mouse Mouse button index (0, 1, 2) or 'WHEEL' for wheel notches
-	 * @param {'CTRL'|'SHIFT'|null} key Keyboard modifier
-	 * @returns {'PAN'|'ROTATE'|'ZOOM'|'FOV'|null} The operation if it has been found, null otherwise
+	 * Return the operation associated to a mouse/keyboard combination.
+	 *
+	 * @private
+	 * @param {0|1|2|'WHEEL'} mouse - Mouse button index (0, 1, 2) or 'WHEEL' for wheel notches.
+	 * @param {'CTRL'|'SHIFT'|null} key - Keyboard modifier.
+	 * @returns {'PAN'|'ROTATE'|'ZOOM'|'FOV'|null} The operation if it has been found, `null` otherwise.
 	 */
 	getOpFromAction( mouse, key ) {
 
@@ -1247,10 +1455,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Get the operation associated to mouse and key combination and returns the corresponding FSA state
-	 * @param {0|1|2} mouse Mouse button index (0, 1, 2)
-	 * @param {'CTRL'|'SHIFT'|null} key Keyboard modifier
-	 * @returns {?STATE} The FSA state obtained from the operation associated to mouse/keyboard combination
+	 * Get the operation associated to mouse and key combination and returns the corresponding FSA state.
+	 *
+	 * @private
+	 * @param {0|1|2} mouse - Mouse button index (0, 1, 2)
+	 * @param {'CTRL'|'SHIFT'|null} key - Keyboard modifier
+	 * @returns {?STATE} The FSA state obtained from the operation associated to mouse/keyboard combination.
 	 */
 	getOpStateFromAction( mouse, key ) {
 
@@ -1287,10 +1497,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the angle between two pointers
-	 * @param {PointerEvent} p1
-	 * @param {PointerEvent} p2
-	 * @returns {number} The angle between two pointers in degrees
+	 * Calculate the angle between two pointers.
+	 *
+	 * @private
+	 * @param {PointerEvent} p1 - The first pointer event.
+	 * @param {PointerEvent} p2 - The second pointer event.
+	 * @returns {number} The angle between two pointers in degrees.
 	 */
 	getAngle( p1, p2 ) {
 
@@ -1299,8 +1511,10 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Update a PointerEvent inside current pointerevents array
-	 * @param {PointerEvent} event
+	 * Updates a PointerEvent inside current pointerevents array.
+	 *
+	 * @private
+	 * @param {PointerEvent} event - The pointer event.
 	 */
 	updateTouchEvent( event ) {
 
@@ -1318,8 +1532,10 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Apply a transformation matrix, to the camera and gizmos
-	 * @param {Object} transformation Object containing matrices to apply to camera and gizmos
+	 * Applys a transformation matrix, to the camera and gizmos.
+	 *
+	 * @private
+	 * @param {Object} transformation - Object containing matrices to apply to camera and gizmos.
 	 */
 	applyTransformMatrix( transformation ) {
 
@@ -1405,13 +1621,14 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the angular speed
+	 * Calculates the angular speed.
 	 *
-	 * @param {number} p0 Position at t0
-	 * @param {number} p1 Position at t1
-	 * @param {number} t0 Initial time in milliseconds
-	 * @param {number} t1 Ending time in milliseconds
-	 * @returns {number}
+	 * @private
+	 * @param {number} p0 - Position at t0.
+	 * @param {number} p1 - Position at t1.
+	 * @param {number} t0 - Initial time in milliseconds.
+	 * @param {number} t1 - Ending time in milliseconds.
+	 * @returns {number} The angular speed.
 	 */
 	calculateAngularSpeed( p0, p1, t0, t1 ) {
 
@@ -1428,10 +1645,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the distance between two pointers
-	 * @param {PointerEvent} p0 The first pointer
-	 * @param {PointerEvent} p1 The second pointer
-	 * @returns {number} The distance between the two pointers
+	 * Calculates the distance between two pointers.
+	 *
+	 * @private
+	 * @param {PointerEvent} p0 - The first pointer.
+	 * @param {PointerEvent} p1 - The second pointer.
+	 * @returns {number} The distance between the two pointers.
 	 */
 	calculatePointersDistance( p0, p1 ) {
 
@@ -1440,10 +1659,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the rotation axis as the vector perpendicular between two vectors
-	 * @param {Vector3} vec1 The first vector
-	 * @param {Vector3} vec2 The second vector
-	 * @returns {Vector3} The normalized rotation axis
+	 * Calculates the rotation axis as the vector perpendicular between two vectors.
+	 *
+	 * @private
+	 * @param {Vector3} vec1 - The first vector.
+	 * @param {Vector3} vec2 - The second vector.
+	 * @returns {Vector3} The normalized rotation axis.
 	 */
 	calculateRotationAxis( vec1, vec2 ) {
 
@@ -1456,9 +1677,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the trackball radius so that gizmo's diameter will be 2/3 of the minimum side of the camera frustum
-	 * @param {Camera} camera
-	 * @returns {number} The trackball radius
+	 * Calculates the trackball radius so that gizmo's diameter will be 2/3 of the minimum side of the camera frustum.
+	 *
+	 * @private
+	 * @param {Camera} camera - The camera.
+	 * @returns {number} The trackball radius.
 	 */
 	calculateTbRadius( camera ) {
 
@@ -1479,10 +1702,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Focus operation consist of positioning the point of interest in front of the camera and a slightly zoom in
-	 * @param {Vector3} point The point of interest
-	 * @param {number} size Scale factor
-	 * @param {number} [amount=1] Amount of operation to be completed (used for focus animations, default is complete full operation)
+	 * Focus operation consist of positioning the point of interest in front of the camera and a slightly zoom in.
+	 *
+	 * @private
+	 * @param {Vector3} point - The point of interest.
+	 * @param {number} size - Scale factor.
+	 * @param {number} [amount=1] - Amount of operation to be completed (used for focus animations, default is complete full operation).
 	 */
 	focus( point, size, amount = 1 ) {
 
@@ -1511,7 +1736,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Draw a grid and add it to the scene
+	 * Creates a grid if necessary and adds it to the scene.
+	 *
+	 * @private
 	 */
 	drawGrid() {
 
@@ -1562,9 +1789,6 @@ class ArcballControls extends Controls {
 
 	}
 
-	/**
-	 * Remove all listeners, stop animations and clean scene
-	 */
 	dispose() {
 
 		if ( this._animationId != - 1 ) {
@@ -1581,7 +1805,7 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * remove the grid from the scene
+	 * Removes the grid from the scene.
 	 */
 	disposeGrid() {
 
@@ -1595,9 +1819,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Compute the easing out cubic function for ease out effect in animation
-	 * @param {number} t The absolute progress of the animation in the bound of 0 (beginning of the) and 1 (ending of animation)
-	 * @returns {number} Result of easing out cubic at time t
+	 * Computes the easing out cubic function for ease out effect in animation.
+	 *
+	 * @private
+	 * @param {number} t - The absolute progress of the animation in the bound of `0` (beginning of the) and `1` (ending of animation).
+	 * @returns {number} Result of easing out cubic at time `t`.
 	 */
 	easeOutCubic( t ) {
 
@@ -1606,8 +1832,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Make rotation gizmos more or less visible
-	 * @param {boolean} isActive If true, make gizmos more visible
+	 * Makes rotation gizmos more or less visible.
+	 *
+	 * @param {boolean} isActive - If set to `true`, gizmos are more visible.
 	 */
 	activateGizmos( isActive ) {
 
@@ -1632,12 +1859,13 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the cursor position in NDC
+	 * Calculates the cursor position in NDC.
 	 *
-	 * @param {number} cursorX Cursor horizontal coordinate within the canvas
-	 * @param {number} cursorY Cursor vertical coordinate within the canvas
-	 * @param {HTMLElement} canvas The canvas where the renderer draws its output
-	 * @returns {Vector2} Cursor normalized position inside the canvas
+	 * @private
+	 * @param {number} cursorX - Cursor horizontal coordinate within the canvas.
+	 * @param {number} cursorY - Cursor vertical coordinate within the canvas.
+	 * @param {HTMLElement} canvas - The canvas where the renderer draws its output.
+	 * @returns {Vector2} Cursor normalized position inside the canvas.
 	 */
 	getCursorNDC( cursorX, cursorY, canvas ) {
 
@@ -1649,12 +1877,13 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Calculate the cursor position inside the canvas x/y coordinates with the origin being in the center of the canvas
+	 * Calculates the cursor position inside the canvas x/y coordinates with the origin being in the center of the canvas.
 	 *
-	 * @param {number} cursorX Cursor horizontal coordinate within the canvas
-	 * @param {number} cursorY Cursor vertical coordinate within the canvas
-	 * @param {HTMLElement} canvas The canvas where the renderer draws its output
-	 * @returns {Vector2} Cursor position inside the canvas
+	 * @private
+	 * @param {number} cursorX - Cursor horizontal coordinate within the canvas.
+	 * @param {number} cursorY - Cursor vertical coordinate within the canvas.
+	 * @param {HTMLElement} canvas - The canvas where the renderer draws its output.
+	 * @returns {Vector2} Cursor position inside the canvas.
 	 */
 	getCursorPosition( cursorX, cursorY, canvas ) {
 
@@ -1666,8 +1895,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set the camera to be controlled
-	 * @param {Camera} camera The virtual camera to be controlled
+	 * Sets the camera to be controlled.  Must be called in order to set a new camera to be controlled.
+	 *
+	 * @param {Camera} camera - The camera to be controlled.
 	 */
 	setCamera( camera ) {
 
@@ -1709,8 +1939,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set gizmos visibility
-	 * @param {boolean} value Value of gizmos visibility
+	 * Sets gizmos visibility.
+	 *
+	 * @param {boolean} value - Value of gizmos visibility.
 	 */
 	setGizmosVisible( value ) {
 
@@ -1720,8 +1951,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set gizmos radius factor and redraws gizmos
-	 * @param {number} value Value of radius factor
+	 * Sets gizmos radius factor and redraws gizmos.
+	 *
+	 * @param {number} value - Value of radius factor.
 	 */
 	setTbRadius( value ) {
 
@@ -1744,9 +1976,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Creates the rotation gizmos matching trackball center and radius
-	 * @param {Vector3} tbCenter The trackball center
-	 * @param {number} tbRadius The trackball radius
+	 * Creates the rotation gizmos matching trackball center and radius.
+	 *
+	 * @private
+	 * @param {Vector3} tbCenter - The trackball center.
+	 * @param {number} tbRadius - The trackball radius.
 	 */
 	makeGizmos( tbCenter, tbRadius ) {
 
@@ -1814,11 +2048,13 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Perform animation for focus operation
-	 * @param {number} time Instant in which this function is called as performance.now()
-	 * @param {Vector3} point Point of interest for focus operation
-	 * @param {Matrix4} cameraMatrix Camera matrix
-	 * @param {Matrix4} gizmoMatrix Gizmos matrix
+	 * Performs animation for focus operation.
+	 *
+	 * @private
+	 * @param {number} time - Instant in which this function is called as performance.now().
+	 * @param {Vector3} point - Point of interest for focus operation.
+	 * @param {Matrix4} cameraMatrix - Camera matrix.
+	 * @param {Matrix4} gizmoMatrix - Gizmos matrix.
 	 */
 	onFocusAnim( time, point, cameraMatrix, gizmoMatrix ) {
 
@@ -1880,10 +2116,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Perform animation for rotation operation
-	 * @param {number} time Instant in which this function is called as performance.now()
-	 * @param {Vector3} rotationAxis Rotation axis
-	 * @param {number} w0 Initial angular velocity
+	 * Performs animation for rotation operation.
+	 *
+	 * @private
+	 * @param {number} time - Instant in which this function is called as performance.now().
+	 * @param {Vector3} rotationAxis - Rotation axis.
+	 * @param {number} w0 - Initial angular velocity.
 	 */
 	onRotationAnim( time, rotationAxis, w0 ) {
 
@@ -1947,11 +2185,12 @@ class ArcballControls extends Controls {
 
 
 	/**
-	 * Perform pan operation moving camera between two points
+	 * Performs pan operation moving camera between two points.
 	 *
-	 * @param {Vector3} p0 Initial point
-	 * @param {Vector3} p1 Ending point
-	 * @param {boolean} [adjust=false] If movement should be adjusted considering camera distance (Perspective only)
+	 * @private
+	 * @param {Vector3} p0 - Initial point.
+	 * @param {Vector3} p1 - Ending point.
+	 * @param {boolean} [adjust=false] - If movement should be adjusted considering camera distance (Perspective only).
 	 * @returns {Object}
 	 */
 	pan( p0, p1, adjust = false ) {
@@ -1983,7 +2222,7 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Reset trackball
+	 * Resets the controls.
 	 */
 	reset() {
 
@@ -2020,10 +2259,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Rotate the camera around an axis passing by trackball's center
-	 * @param {Vector3} axis Rotation axis
-	 * @param {number} angle Angle in radians
-	 * @returns {Object} Object with 'camera' field containing transformation matrix resulting from the operation to be applied to the camera
+	 * Rotates the camera around an axis passing by trackball's center.
+	 *
+	 * @private
+	 * @param {Vector3} axis - Rotation axis.
+	 * @param {number} angle - Angle in radians.
+	 * @returns {Object} Object with 'camera' field containing transformation matrix resulting from the operation to be applied to the camera.
 	 */
 	rotate( axis, angle ) {
 
@@ -2042,6 +2283,9 @@ class ArcballControls extends Controls {
 
 	}
 
+	/**
+	 * Copy the current state to clipboard (as a readable JSON text).
+	 */
 	copyState() {
 
 		let state;
@@ -2080,6 +2324,10 @@ class ArcballControls extends Controls {
 
 	}
 
+	/**
+	 * Set the controls state from the clipboard, assumes that the clipboard stores a JSON
+	 * text as saved from `copyState()`.
+	 */
 	pasteState() {
 
 		const self = this;
@@ -2092,7 +2340,7 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Save the current state of the control. This can later be recover with .reset
+	 * Saves the current state of the control. This can later be recover with `reset()`.
 	 */
 	saveState() {
 
@@ -2112,11 +2360,13 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Perform uniform scale operation around a given point
-	 * @param {number} size Scale factor
-	 * @param {Vector3} point Point around which scale
-	 * @param {boolean} scaleGizmos If gizmos should be scaled (Perspective only)
-	 * @returns {Object} Object with 'camera' and 'gizmo' fields containing transformation matrices resulting from the operation to be applied to the camera and gizmos
+	 * Performs uniform scale operation around a given point.
+	 *
+	 * @private
+	 * @param {number} size - Scale factor.
+	 * @param {Vector3} point - Point around which scale.
+	 * @param {boolean} scaleGizmos - If gizmos should be scaled (Perspective only).
+	 * @returns {Object} Object with 'camera' and 'gizmo' fields containing transformation matrices resulting from the operation to be applied to the camera and gizmos.
 	 */
 	scale( size, point, scaleGizmos = true ) {
 
@@ -2228,8 +2478,10 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set camera fov
-	 * @param {number} value fov to be set
+	 * Sets camera fov.
+	 *
+	 * @private
+	 * @param {number} value - The FOV to be set.
 	 */
 	setFov( value ) {
 
@@ -2243,10 +2495,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Set values in transformation object
+	 * Sets values in transformation object.
 	 *
-	 * @param {Matrix4} [camera=null] Transformation to be applied to the camera
-	 * @param {Matrix4} [gizmos=null] Transformation to be applied to gizmos
+	 * @private
+	 * @param {Matrix4} [camera=null] - Transformation to be applied to the camera.
+	 * @param {Matrix4} [gizmos=null] - Transformation to be applied to gizmos.
 	 */
 	setTransformationMatrices( camera = null, gizmos = null ) {
 
@@ -2289,11 +2542,12 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Rotate camera around its direction axis passing by a given point by a given angle
+	 * Rotates camera around its direction axis passing by a given point by a given angle.
 	 *
-	 * @param {Vector3} point The point where the rotation axis is passing trough
-	 * @param {number} angle Angle in radians
-	 * @returns {Object} The computed transformation matrix
+	 * @private
+	 * @param {Vector3} point - The point where the rotation axis is passing trough.
+	 * @param {number} angle - Angle in radians.
+	 * @returns {Object} The computed transformation matrix.
 	 */
 	zRotate( point, angle ) {
 
@@ -2315,7 +2569,12 @@ class ArcballControls extends Controls {
 
 	}
 
-
+	/**
+	 * Returns the raycaster that is used for user interaction. This object is shared between all
+	 * instances of `ArcballControls`.
+	 *
+	 * @returns {Raycaster} The internal raycaster.
+	 */
 	getRaycaster() {
 
 		return _raycaster;
@@ -2324,11 +2583,12 @@ class ArcballControls extends Controls {
 
 
 	/**
-	 * Unproject the cursor on the 3D object surface
+	 * Unprojects the cursor on the 3D object surface.
 	 *
-	 * @param {Vector2} cursor Cursor coordinates in NDC
-	 * @param {Camera} camera Virtual camera
-	 * @returns {?Vector3} The point of intersection with the model, if exist, null otherwise
+	 * @private
+	 * @param {Vector2} cursor - Cursor coordinates in NDC.
+	 * @param {Camera} camera - Virtual camera.
+	 * @returns {?Vector3} The point of intersection with the model, if exist, null otherwise.
 	 */
 	unprojectOnObj( cursor, camera ) {
 
@@ -2354,13 +2614,15 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Unproject the cursor on the trackball surface
-	 * @param {Camera} camera The virtual camera
-	 * @param {number} cursorX Cursor horizontal coordinate on screen
-	 * @param {number} cursorY Cursor vertical coordinate on screen
-	 * @param {HTMLElement} canvas The canvas where the renderer draws its output
-	 * @param {number} tbRadius The trackball radius
-	 * @returns {Vector3} The unprojected point on the trackball surface
+	 * Unproject the cursor on the trackball surface.
+	 *
+	 * @private
+	 * @param {Camera} camera - The virtual camera.
+	 * @param {number} cursorX - Cursor horizontal coordinate on screen.
+	 * @param {number} cursorY - Cursor vertical coordinate on screen.
+	 * @param {HTMLElement} canvas - The canvas where the renderer draws its output.
+	 * @param {number} tbRadius - The trackball radius.
+	 * @returns {Vector3} The unprojected point on the trackball surface.
 	 */
 	unprojectOnTbSurface( camera, cursorX, cursorY, canvas, tbRadius ) {
 
@@ -2484,13 +2746,15 @@ class ArcballControls extends Controls {
 
 
 	/**
-	 * Unproject the cursor on the plane passing through the center of the trackball orthogonal to the camera
-	 * @param {Camera} camera The virtual camera
-	 * @param {number} cursorX Cursor horizontal coordinate on screen
-	 * @param {number} cursorY Cursor vertical coordinate on screen
-	 * @param {HTMLElement} canvas The canvas where the renderer draws its output
-	 * @param {boolean} [initialDistance=false] If initial distance between camera and gizmos should be used for calculations instead of current (Perspective only)
-	 * @returns {Vector3} The unprojected point on the trackball plane
+	 * Unprojects the cursor on the plane passing through the center of the trackball orthogonal to the camera.
+	 *
+	 * @private
+	 * @param {Camera} camera - The virtual camera.
+	 * @param {number} cursorX - Cursor horizontal coordinate on screen.
+	 * @param {number} cursorY - Cursor vertical coordinate on screen.
+	 * @param {HTMLElement} canvas - The canvas where the renderer draws its output.
+	 * @param {boolean} [initialDistance=false] - If initial distance between camera and gizmos should be used for calculations instead of current (Perspective only).
+	 * @returns {Vector3} The unprojected point on the trackball plane.
 	 */
 	unprojectOnTbPlane( camera, cursorX, cursorY, canvas, initialDistance = false ) {
 
@@ -2564,7 +2828,9 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Update camera and gizmos state
+	 * Updates camera and gizmos state.
+	 *
+	 * @private
 	 */
 	updateMatrixState() {
 
@@ -2587,9 +2853,11 @@ class ArcballControls extends Controls {
 	}
 
 	/**
-	 * Update the trackball FSA
-	 * @param {STATE} newState New state of the FSA
-	 * @param {boolean} updateMatrices If matrices state should be updated
+	 * Updates the trackball FSA.
+	 *
+	 * @private
+	 * @param {STATE} newState - New state of the FSA.
+	 * @param {boolean} updateMatrices - If matrices state should be updated.
 	 */
 	updateTbState( newState, updateMatrices ) {
 

examples/jsm/controls/DragControls.js

@@ -31,18 +31,79 @@ const STATE = {
 	ROTATE: 1
 };
 
+/**
+ * This class can be used to provide a drag'n'drop interaction.
+ *
+ * ```js
+ * const controls = new DragControls( objects, camera, renderer.domElement );
+ *
+ * // add event listener to highlight dragged objects
+ * controls.addEventListener( 'dragstart', function ( event ) {
+ *
+ * 	event.object.material.emissive.set( 0xaaaaaa );
+ *
+ * } );
+ *
+ * controls.addEventListener( 'dragend', function ( event ) {
+ *
+ * 	event.object.material.emissive.set( 0x000000 );
+ *
+ * } );
+ * ```
+ *
+ * @augments Controls
+ */
 class DragControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Array<Object3D>} objects - An array of draggable 3D objects.
+	 * @param {Camera} camera - The camera of the rendered scene.
+	 * @param {?HTMLDOMElement} [domElement=null] - The HTML DOM element used for event listeners.
+	 */
 	constructor( objects, camera, domElement = null ) {
 
 		super( camera, domElement );
 
+		/**
+		 * An array of draggable 3D objects.
+		 *
+		 * @type {Array<Object3D>}
+		 */
 		this.objects = objects;
 
+		/**
+		 * Whether children of draggable objects can be dragged independently from their parent.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.recursive = true;
+
+		/**
+		 * This option only works if the `objects` array contains a single draggable  group object.
+		 * If set to `true`, the controls does not transform individual objects but the entire group.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.transformGroup = false;
+
+		/**
+		 * The speed at which the object will rotate when dragged in `rotate` mode.
+		 * The higher the number the faster the rotation.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.rotateSpeed = 1;
 
+		/**
+		 * The raycaster used for detecting 3D objects.
+		 *
+		 * @type {Raycaster}
+		 */
 		this.raycaster = new Raycaster();
 
 		// interaction
@@ -407,4 +468,32 @@ function findGroup( obj, group = null ) {
 
 }
 
+/**
+ * Fires when the user drags a 3D object.
+ *
+ * @event DragControls#drag
+ * @type {Object}
+ */
+
+/**
+ * Fires when the user has finished dragging a 3D object.
+ *
+ * @event DragControls#dragend
+ * @type {Object}
+ */
+
+/**
+ * Fires when the pointer is moved onto a 3D object, or onto one of its children.
+ *
+ * @event DragControls#hoveron
+ * @type {Object}
+ */
+
+/**
+ * Fires when the pointer is moved out of a 3D object.
+ *
+ * @event DragControls#hoveroff
+ * @type {Object}
+ */
+
 export { DragControls };

examples/jsm/controls/FirstPersonControls.js

@@ -10,31 +10,127 @@ const _spherical = new Spherical();
 const _target = new Vector3();
 const _targetPosition = new Vector3();
 
+/**
+ * This class is an alternative implementation of {@link FlyControls}.
+ *
+ * @augments Controls
+ */
 class FirstPersonControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( object, domElement = null ) {
 
 		super( object, domElement );
 
-		// API
-
+		/**
+		 * The movement speed.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.movementSpeed = 1.0;
+
+		/**
+		 * The look around speed.
+		 *
+		 * @type {number}
+		 * @default 0.005
+		 */
 		this.lookSpeed = 0.005;
 
+		/**
+		 * Whether it's possible to vertically look around or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.lookVertical = true;
+
+		/**
+		 * Whether the camera is automatically moved forward or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.autoForward = false;
 
+		/**
+		 * Whether it's possible to look around or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.activeLook = true;
 
+		/**
+		 * Whether or not the camera's height influences the forward movement speed.
+		 * Use the properties `heightCoef`, `heightMin` and `heightMax` for configuration.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.heightSpeed = false;
+
+		/**
+		 * Determines how much faster the camera moves when it's y-component is near `heightMax`.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.heightCoef = 1.0;
+
+		/**
+		 * Lower camera height limit used for movement speed adjustment.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.heightMin = 0.0;
+
+		/**
+		 * Upper camera height limit used for movement speed adjustment.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.heightMax = 1.0;
 
+		/**
+		 * Whether or not looking around is vertically constrained by `verticalMin` and `verticalMax`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.constrainVertical = false;
+
+		/**
+		 * How far you can vertically look around, lower limit. Range is `0` to `Math.PI` in radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.verticalMin = 0;
+
+		/**
+		 * How far you can vertically look around, upper limit. Range is `0` to `Math.PI` in radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.verticalMax = Math.PI;
 
+		/**
+		 * Whether the mouse is pressed down or not.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		this.mouseDragOn = false;
 
 		// internals
@@ -108,6 +204,9 @@ class FirstPersonControls extends Controls {
 
 	}
 
+	/**
+	 * Must be called if the application window is resized.
+	 */
 	handleResize() {
 
 		if ( this.domElement === document ) {
@@ -124,6 +223,14 @@ class FirstPersonControls extends Controls {
 
 	}
 
+	/**
+	 * Rotates the camera towards the defined target position.
+	 *
+	 * @param {number|Vector3} x - The x coordinate of the target position or alternatively a vector representing the target position.
+	 * @param {number} y - The y coordinate of the target position.
+	 * @param {number} z - The z coordinate of the target position.
+	 * @return {FirstPersonControls} A reference to this controls.
+	 */
 	lookAt( x, y, z ) {
 
 		if ( x.isVector3 ) {

examples/jsm/controls/FlyControls.js

@@ -4,21 +4,66 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * Fires when the camera has been transformed by the controls.
+ *
+ * @event FlyControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
 
 const _EPS = 0.000001;
 const _tmpQuaternion = new Quaternion();
 
+/**
+ * This class enables a navigation similar to fly modes in DCC tools like Blender.
+ * You can arbitrarily transform the camera in 3D space without any limitations
+ * (e.g. focus on a specific target).
+ *
+ * @augments Controls
+ */
 class FlyControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( object, domElement = null ) {
 
 		super( object, domElement );
 
+		/**
+		 * The movement speed.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.movementSpeed = 1.0;
+
+		/**
+		 * The rotation speed.
+		 *
+		 * @type {number}
+		 * @default 0.005
+		 */
 		this.rollSpeed = 0.005;
 
+		/**
+		 * If set to `true`, you can only look around by performing a drag interaction.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.dragToLook = false;
+
+		/**
+		 * If set to `true`, the camera automatically moves forward (and does not stop) when initially translated.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.autoForward = false;
 
 		// internals

examples/jsm/controls/MapControls.js

@@ -2,23 +2,56 @@ import { MOUSE, TOUCH } from 'three';
 
 import { OrbitControls } from './OrbitControls.js';
 
-// MapControls performs orbiting, dollying (zooming), and panning.
-// Unlike TrackballControls, it maintains the "up" direction object.up (+Y by default).
-//
-//    Orbit - right mouse, or left mouse + ctrl/meta/shiftKey / touch: two-finger rotate
-//    Zoom - middle mouse, or mousewheel / touch: two-finger spread or squish
-//    Pan - left mouse, or arrow keys / touch: one-finger move
-
+/**
+ * This class is intended for transforming a camera over a map from bird's eye perspective.
+ * The class shares its implementation with {@link OrbitControls} but uses a specific preset
+ * for mouse/touch interaction and disables screen space panning by default.
+ *
+ * - Orbit: Right mouse, or left mouse + ctrl/meta/shiftKey / touch: two-finger rotate.
+ * - Zoom: Middle mouse, or mousewheel / touch: two-finger spread or squish.
+ * - Pan: Left mouse, or arrow keys / touch: one-finger move.
+ *
+ * @augments OrbitControls
+ */
 class MapControls extends OrbitControls {
 
 	constructor( object, domElement ) {
 
 		super( object, domElement );
 
-		this.screenSpacePanning = false; // pan orthogonal to world-space direction camera.up
-
+		/**
+		 * Overwritten and set to `false` to pan orthogonal to world-space direction `camera.up`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.screenSpacePanning = false;
+
+		/**
+		 * This object contains references to the mouse actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	LEFT: THREE.MOUSE.PAN,
+		 * 	MIDDLE: THREE.MOUSE.DOLLY,
+		 * 	RIGHT: THREE.MOUSE.ROTATE
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.mouseButtons = { LEFT: MOUSE.PAN, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.ROTATE };
 
+		/**
+		 * This object contains references to the touch actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	ONE: THREE.TOUCH.PAN,
+		 * 	TWO: THREE.TOUCH.DOLLY_ROTATE
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.touches = { ONE: TOUCH.PAN, TWO: TOUCH.DOLLY_ROTATE };
 
 	}

examples/jsm/controls/OrbitControls.js

@@ -11,16 +11,30 @@ import {
 	MathUtils
 } from 'three';
 
-// OrbitControls performs orbiting, dollying (zooming), and panning.
-// Unlike TrackballControls, it maintains the "up" direction object.up (+Y by default).
-//
-//    Orbit - left mouse / touch: one-finger move
-//    Zoom - middle mouse, or mousewheel / touch: two-finger spread or squish
-//    Pan - right mouse, or left mouse + ctrl/meta/shiftKey, or arrow keys / touch: two-finger move
-
+/**
+ * Fires when the camera has been transformed by the controls.
+ *
+ * @event OrbitControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires when an interaction was initiated.
+ *
+ * @event OrbitControls#start
+ * @type {Object}
+ */
 const _startEvent = { type: 'start' };
+
+/**
+ * Fires when an interaction has finished.
+ *
+ * @event OrbitControls#end
+ * @type {Object}
+ */
 const _endEvent = { type: 'end' };
+
 const _ray = new Ray();
 const _plane = new Plane();
 const _TILT_LIMIT = Math.cos( 70 * MathUtils.DEG2RAD );
@@ -40,84 +54,340 @@ const _STATE = {
 };
 const _EPS = 0.000001;
 
+
+/**
+ * Orbit controls allow the camera to orbit around a target.
+ *
+ * OrbitControls performs orbiting, dollying (zooming), and panning. Unlike {@link TrackballControls},
+ * it maintains the "up" direction `object.up` (+Y by default).
+ *
+ * - Orbit: Left mouse / touch: one-finger move.
+ * - Zoom: Middle mouse, or mousewheel / touch: two-finger spread or squish.
+ * - Pan: Right mouse, or left mouse + ctrl/meta/shiftKey, or arrow keys / touch: two-finger move.
+ *
+ * ```js
+ * const controls = new OrbitControls( camera, renderer.domElement );
+ *
+ * // controls.update() must be called after any manual changes to the camera's transform
+ * camera.position.set( 0, 20, 100 );
+ * controls.update();
+ *
+ * function animate() {
+ *
+ * 	// required if controls.enableDamping or controls.autoRotate are set to true
+ * 	controls.update();
+ *
+ * 	renderer.render( scene, camera );
+ *
+ * }
+ * ```
+ *
+ * @augments Controls
+ */
 class OrbitControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( object, domElement = null ) {
 
 		super( object, domElement );
 
 		this.state = _STATE.NONE;
 
-		// Set to false to disable this control
-		this.enabled = true;
-
-		// "target" sets the location of focus, where the object orbits around
+		/**
+		 * The focus point of the controls, the `object` orbits around this.
+		 * It can be updated manually at any point to change the focus of the controls.
+		 *
+		 * @type {Vector3}
+		 */
 		this.target = new Vector3();
 
-		// Sets the 3D cursor (similar to Blender), from which the maxTargetRadius takes effect
+		/**
+		 * The focus point of the `minTargetRadius` and `maxTargetRadius` limits.
+		 * It can be updated manually at any point to change the center of interest
+		 * for the `target`.
+		 *
+		 * @type {Vector3}
+		 */
 		this.cursor = new Vector3();
 
-		// How far you can dolly in and out ( PerspectiveCamera only )
+		/**
+		 * How far you can dolly in (perspective camera only).
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minDistance = 0;
+
+		/**
+		 * How far you can dolly out (perspective camera only).
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxDistance = Infinity;
 
-		// How far you can zoom in and out ( OrthographicCamera only )
+		/**
+		 * How far you can zoom in (orthographic camera only).
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minZoom = 0;
+
+		/**
+		 * How far you can zoom out (orthographic camera only).
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxZoom = Infinity;
 
-		// Limit camera target within a spherical area around the cursor
+		/**
+		 * How close you can get the target to the 3D `cursor`.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minTargetRadius = 0;
-		this.maxTargetRadius = Infinity;
-
-		// How far you can orbit vertically, upper and lower limits.
-		// Range is 0 to Math.PI radians.
-		this.minPolarAngle = 0; // radians
-		this.maxPolarAngle = Math.PI; // radians
 
-		// How far you can orbit horizontally, upper and lower limits.
-		// If set, the interval [ min, max ] must be a sub-interval of [ - 2 PI, 2 PI ], with ( max - min < 2 PI )
-		this.minAzimuthAngle = - Infinity; // radians
-		this.maxAzimuthAngle = Infinity; // radians
+		/**
+		 * How far you can move the target from the 3D `cursor`.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
+		this.maxTargetRadius = Infinity;
 
-		// Set to true to enable damping (inertia)
-		// If damping is enabled, you must call controls.update() in your animation loop
+		/**
+		 * How far you can orbit vertically, lower limit. Range is `[0, Math.PI]` radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.minPolarAngle = 0;
+
+		/**
+		 * How far you can orbit vertically, upper limit. Range is `[0, Math.PI]` radians.
+		 *
+		 * @type {number}
+		 * @default Math.PI
+		 */
+		this.maxPolarAngle = Math.PI;
+
+		/**
+		 * How far you can orbit horizontally, lower limit. If set, the interval `[ min, max ]`
+		 * must be a sub-interval of `[ - 2 PI, 2 PI ]`, with `( max - min < 2 PI )`.
+		 *
+		 * @type {number}
+		 * @default -Infinity
+		 */
+		this.minAzimuthAngle = - Infinity;
+
+		/**
+		 * How far you can orbit horizontally, upper limit. If set, the interval `[ min, max ]`
+		 * must be a sub-interval of `[ - 2 PI, 2 PI ]`, with `( max - min < 2 PI )`.
+		 *
+		 * @type {number}
+		 * @default -Infinity
+		 */
+		this.maxAzimuthAngle = Infinity;
+
+		/**
+		 * Set to `true` to enable damping (inertia), which can be used to give a sense of weight
+		 * to the controls. Note that if this is enabled, you must call `update()` in your animation
+		 * loop.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.enableDamping = false;
+
+		/**
+		 * The damping inertia used if `enableDamping` is set to `true`.
+		 *
+		 * Note that for this to work, you must call `update()` in your animation loop.
+		 *
+		 * @type {number}
+		 * @default 0.05
+		 */
 		this.dampingFactor = 0.05;
 
-		// This option actually enables dollying in and out; left as "zoom" for backwards compatibility.
-		// Set to false to disable zooming
+		/**
+		 * Enable or disable zooming (dollying) of the camera.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enableZoom = true;
+
+		/**
+		 * Speed of zooming / dollying.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.zoomSpeed = 1.0;
 
-		// Set to false to disable rotating
+		/**
+		 * Enable or disable horizontal and vertical rotation of the camera.
+		 *
+		 * Note that it is possible to disable a single axis by setting the min and max of the
+		 * `minPolarAngle` or `minAzimuthAngle` to the same value, which will cause the vertical
+		 * or horizontal rotation to be fixed at that value.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enableRotate = true;
+
+		/**
+		 * Speed of rotation.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.rotateSpeed = 1.0;
+
+		/**
+		 * How fast to rotate the camera when the keyboard is used.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.keyRotateSpeed = 1.0;
 
-		// Set to false to disable panning
+		/**
+		 * Enable or disable camera panning.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enablePan = true;
+
+		/**
+		 * Speed of panning.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.panSpeed = 1.0;
-		this.screenSpacePanning = true; // if false, pan orthogonal to world-space direction camera.up
-		this.keyPanSpeed = 7.0;	// pixels moved per arrow key push
+
+		/**
+		 * Defines how the camera's position is translated when panning. If `true`, the camera pans
+		 * in screen space. Otherwise, the camera pans in the plane orthogonal to the camera's up
+		 * direction.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.screenSpacePanning = true;
+
+		/**
+		 * How fast to pan the camera when the keyboard is used in
+		 * pixels per keypress.
+		 *
+		 * @type {number}
+		 * @default 7
+		 */
+		this.keyPanSpeed = 7.0;
+
+		/**
+		 * Setting this property to `true` allows to zoom to the cursor's position.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.zoomToCursor = false;
 
-		// Set to true to automatically rotate around the target
-		// If auto-rotate is enabled, you must call controls.update() in your animation loop
+		/**
+		 * Set to true to automatically rotate around the target
+		 *
+		 * Note that if this is enabled, you must call `update()` in your animation loop.
+		 * If you want the auto-rotate speed to be independent of the frame rate (the refresh
+		 * rate of the display), you must pass the time `deltaTime`, in seconds, to `update()`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.autoRotate = false;
-		this.autoRotateSpeed = 2.0; // 30 seconds per orbit when fps is 60
 
-		// The four arrow keys
+		/**
+		 * How fast to rotate around the target if `autoRotate` is `true`. The default  equates to 30 seconds
+		 * per orbit at 60fps.
+		 *
+		 * Note that if `autoRotate` is enabled, you must call `update()` in your animation loop.
+		 *
+		 * @type {number}
+		 * @default 2
+		 */
+		this.autoRotateSpeed = 2.0;
+
+		/**
+		 * This object contains references to the keycodes for controlling camera panning.
+		 *
+		 * ```js
+		 * controls.keys = {
+		 * 	LEFT: 'ArrowLeft', //left arrow
+		 * 	UP: 'ArrowUp', // up arrow
+		 * 	RIGHT: 'ArrowRight', // right arrow
+		 * 	BOTTOM: 'ArrowDown' // down arrow
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.keys = { LEFT: 'ArrowLeft', UP: 'ArrowUp', RIGHT: 'ArrowRight', BOTTOM: 'ArrowDown' };
 
-		// Mouse buttons
+		/**
+		 * This object contains references to the mouse actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	LEFT: THREE.MOUSE.ROTATE,
+		 * 	MIDDLE: THREE.MOUSE.DOLLY,
+		 * 	RIGHT: THREE.MOUSE.PAN
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.mouseButtons = { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.PAN };
 
-		// Touch fingers
+		/**
+		 * This object contains references to the touch actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	ONE: THREE.TOUCH.ROTATE,
+		 * 	TWO: THREE.TOUCH.DOLLY_PAN
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.touches = { ONE: TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN };
 
-		// for reset
+		/**
+		 * Used internally by `saveState()` and `reset()`.
+		 *
+		 * @type {Vector3}
+		 */
 		this.target0 = this.target.clone();
+
+		/**
+		 * Used internally by `saveState()` and `reset()`.
+		 *
+		 * @type {Vector3}
+		 */
 		this.position0 = this.object.position.clone();
+
+		/**
+		 * Used internally by `saveState()` and `reset()`.
+		 *
+		 * @type {number}
+		 */
 		this.zoom0 = this.object.zoom;
 
 		// the target DOM element for key events
@@ -231,24 +501,45 @@ class OrbitControls extends Controls {
 
 	}
 
+	/**
+	 * Get the current vertical rotation, in radians.
+	 *
+	 * @return {number} The current vertical rotation, in radians.
+	 */
 	getPolarAngle() {
 
 		return this._spherical.phi;
 
 	}
 
+	/**
+	 * Get the current horizontal rotation, in radians.
+	 *
+	 * @return {number} The current horizontal rotation, in radians.
+	 */
 	getAzimuthalAngle() {
 
 		return this._spherical.theta;
 
 	}
 
+	/**
+	 * Returns the distance from the camera to the target.
+	 *
+	 * @return {number} The distance from the camera to the target.
+	 */
 	getDistance() {
 
 		return this.object.position.distanceTo( this.target );
 
 	}
 
+	/**
+	 * Adds key event listeners to the given DOM element.
+	 * `window` is a recommended argument for using this method.
+	 *
+	 * @param {HTMLDOMElement} domElement - The DOM element
+	 */
 	listenToKeyEvents( domElement ) {
 
 		domElement.addEventListener( 'keydown', this._onKeyDown );
@@ -256,6 +547,9 @@ class OrbitControls extends Controls {
 
 	}
 
+	/**
+	 * Removes the key event listener previously defined with `listenToKeyEvents()`.
+	 */
 	stopListenToKeyEvents() {
 
 		if ( this._domElementKeyEvents !== null ) {
@@ -267,6 +561,9 @@ class OrbitControls extends Controls {
 
 	}
 
+	/**
+	 * Save the current state of the controls. This can later be recovered with `reset()`.
+	 */
 	saveState() {
 
 		this.target0.copy( this.target );
@@ -275,6 +572,10 @@ class OrbitControls extends Controls {
 
 	}
 
+	/**
+	 * Reset the controls to their state from either the last time the `saveState()`
+	 * was called, or the initial state.
+	 */
 	reset() {
 
 		this.target.copy( this.target0 );

examples/jsm/controls/PointerLockControls.js

@@ -7,25 +7,98 @@ import {
 const _euler = new Euler( 0, 0, 0, 'YXZ' );
 const _vector = new Vector3();
 
+/**
+ * Fires when the user moves the mouse.
+ *
+ * @event PointerLockControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires when the pointer lock status is "locked" (in other words: the mouse is captured).
+ *
+ * @event PointerLockControls#lock
+ * @type {Object}
+ */
 const _lockEvent = { type: 'lock' };
+
+/**
+ * Fires when the pointer lock status is "unlocked" (in other words: the mouse is not captured anymore).
+ *
+ * @event PointerLockControls#unlock
+ * @type {Object}
+ */
 const _unlockEvent = { type: 'unlock' };
 
 const _PI_2 = Math.PI / 2;
 
+/**
+ * The implementation of this class is based on the [Pointer Lock API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API}.
+ * `PointerLockControls` is a perfect choice for first person 3D games.
+ *
+ * ```js
+ * const controls = new PointerLockControls( camera, document.body );
+ *
+ * // add event listener to show/hide a UI (e.g. the game's menu)
+ * controls.addEventListener( 'lock', function () {
+ *
+ * 	menu.style.display = 'none';
+ *
+ * } );
+ *
+ * controls.addEventListener( 'unlock', function () {
+ *
+ * 	menu.style.display = 'block';
+ *
+ * } );
+ * ```
+ *
+ * @augments Controls
+ */
 class PointerLockControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Camera} camera - The camera that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( camera, domElement = null ) {
 
 		super( camera, domElement );
 
+		/**
+		 * Whether the controls are locked or not.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		this.isLocked = false;
 
-		// Set to constrain the pitch of the camera
-		// Range is 0 to Math.PI radians
-		this.minPolarAngle = 0; // radians
-		this.maxPolarAngle = Math.PI; // radians
-
+		/**
+		 * Camera pitch, lower limit. Range is '[0, Math.PI]' in radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.minPolarAngle = 0;
+
+		/**
+		 * Camera pitch, upper limit. Range is '[0, Math.PI]' in radians.
+		 *
+		 * @type {number}
+		 * @default Math.PI
+		 */
+		this.maxPolarAngle = Math.PI;
+
+		/**
+		 * Multiplier for how much the pointer movement influences the camera rotation.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.pointerSpeed = 1.0;
 
 		// event listeners
@@ -72,12 +145,23 @@ class PointerLockControls extends Controls {
 
 	}
 
+	/**
+	 * Returns the look direction of the camera.
+	 *
+	 * @param {Vector3} v - The target vector that is used to store the method's result.
+	 * @return {Vector3} The normalized direction vector.
+	 */
 	getDirection( v ) {
 
 		return v.set( 0, 0, - 1 ).applyQuaternion( this.object.quaternion );
 
 	}
 
+	/**
+	 * Moves the camera forward parallel to the xz-plane. Assumes camera.up is y-up.
+	 *
+	 * @param {number} distance - The signed distance.
+	 */
 	moveForward( distance ) {
 
 		if ( this.enabled === false ) return;
@@ -95,6 +179,11 @@ class PointerLockControls extends Controls {
 
 	}
 
+	/**
+	 * Moves the camera sidewards parallel to the xz-plane.
+	 *
+	 * @param {number} distance - The signed distance.
+	 */
 	moveRight( distance ) {
 
 		if ( this.enabled === false ) return;
@@ -107,12 +196,18 @@ class PointerLockControls extends Controls {
 
 	}
 
+	/**
+	 * Activates the pointer lock.
+	 */
 	lock() {
 
 		this.domElement.requestPointerLock();
 
 	}
 
+	/**
+	 * Exits the pointer lock.
+	 */
 	unlock() {
 
 		this.domElement.ownerDocument.exitPointerLock();

examples/jsm/controls/TrackballControls.js

@@ -7,8 +7,28 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * Fires when the camera has been transformed by the controls.
+ *
+ * @event TrackballControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires when an interaction was initiated.
+ *
+ * @event TrackballControls#start
+ * @type {Object}
+ */
 const _startEvent = { type: 'start' };
+
+/**
+ * Fires when an interaction has finished.
+ *
+ * @event TrackballControls#end
+ * @type {Object}
+ */
 const _endEvent = { type: 'end' };
 
 const _EPS = 0.000001;
@@ -25,45 +45,168 @@ const _objectUpDirection = new Vector3();
 const _objectSidewaysDirection = new Vector3();
 const _moveDirection = new Vector3();
 
+/**
+ * This class is similar to {@link OrbitControls}. However, it does not maintain a constant camera
+ * `up` vector. That means if the camera orbits over the “north” and “south” poles, it does not flip
+ * to stay "right side up".
+ *
+ * @augments Controls
+ */
 class TrackballControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( object, domElement = null ) {
 
 		super( object, domElement );
 
-		// API
-
-		this.enabled = true;
-
+		/**
+		 * Represents the properties of the screen. Automatically set when `handleResize()` is called.
+		 *
+		 * @type {Object}
+		 * @readonly
+		 */
 		this.screen = { left: 0, top: 0, width: 0, height: 0 };
 
+		/**
+		 * The rotation speed.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.rotateSpeed = 1.0;
+
+		/**
+		 * The zoom speed.
+		 *
+		 * @type {number}
+		 * @default 1.2
+		 */
 		this.zoomSpeed = 1.2;
+
+		/**
+		 * The pan speed.
+		 *
+		 * @type {number}
+		 * @default 0.3
+		 */
 		this.panSpeed = 0.3;
 
+		/**
+		 * Whether rotation is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.noRotate = false;
+
+		/**
+		 * Whether zooming is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.noZoom = false;
+
+		/**
+		 * Whether panning is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.noPan = false;
 
+		/**
+		 * Whether damping is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.staticMoving = false;
+
+		/**
+		 * Defines the intensity of damping. Only considered if `staticMoving` is set to `false`.
+		 *
+		 * @type {number}
+		 * @default 0.2
+		 */
 		this.dynamicDampingFactor = 0.2;
 
+		/**
+		 * How far you can dolly in (perspective camera only).
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minDistance = 0;
+
+		/**
+		 * How far you can dolly out (perspective camera only).
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxDistance = Infinity;
 
+		/**
+		 * How far you can zoom in (orthographic camera only).
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minZoom = 0;
+
+		/**
+		 * How far you can zoom out (orthographic camera only).
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxZoom = Infinity;
 
+		/**
+		 * This array holds keycodes for controlling interactions.
+		 *
+		 * - When the first defined key is pressed, all mouse interactions (left, middle, right) performs orbiting.
+		 * - When the second defined key is pressed, all mouse interactions (left, middle, right) performs zooming.
+		 * - When the third defined key is pressed, all mouse interactions (left, middle, right) performs panning.
+		 *
+		 * Default is *KeyA, KeyS, KeyD* which represents A, S, D.
+		 *
+		 * @type {Array<string>}
+		 */
 		this.keys = [ 'KeyA' /*A*/, 'KeyS' /*S*/, 'KeyD' /*D*/ ];
 
+		/**
+		 * This object contains references to the mouse actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	LEFT: THREE.MOUSE.ROTATE,
+		 * 	MIDDLE: THREE.MOUSE.DOLLY,
+		 * 	RIGHT: THREE.MOUSE.PAN
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.mouseButtons = { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.PAN };
-		this.state = _STATE.NONE;
-		this.keyState = _STATE.NONE;
 
+		/**
+		 * The focus point of the controls.
+		 *
+		 * @type {Vector3}
+		 */
 		this.target = new Vector3();
 
 		// internals
 
+		this.state = _STATE.NONE;
+		this.keyState = _STATE.NONE;
+
 		this._lastPosition = new Vector3();
 		this._lastZoom = 1;
 		this._touchZoomDistanceStart = 0;
@@ -161,6 +304,9 @@ class TrackballControls extends Controls {
 
 	}
 
+	/**
+	 * Must be called if the application window is resized.
+	 */
 	handleResize() {
 
 		const box = this.domElement.getBoundingClientRect();
@@ -233,6 +379,9 @@ class TrackballControls extends Controls {
 
 	}
 
+	/**
+	 * Resets the controls to its initial state.
+	 */
 	reset() {
 
 		this.state = _STATE.NONE;

examples/jsm/controls/TransformControls.js

@@ -32,13 +32,55 @@ const _unit = {
 	Z: new Vector3( 0, 0, 1 )
 };
 
+/**
+ * Fires if any type of change (object or property change) is performed. Property changes
+ * are separate events you can add event listeners to. The event type is "propertyname-changed".
+ *
+ * @event TransformControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires if a pointer (mouse/touch) becomes active.
+ *
+ * @event TransformControls#mouseDown
+ * @type {Object}
+ */
 const _mouseDownEvent = { type: 'mouseDown', mode: null };
+
+/**
+ * Fires if a pointer (mouse/touch) is no longer active.
+ *
+ * @event TransformControls#mouseUp
+ * @type {Object}
+ */
 const _mouseUpEvent = { type: 'mouseUp', mode: null };
+
+/**
+ * Fires if the controlled 3D object is changed.
+ *
+ * @event TransformControls#objectChange
+ * @type {Object}
+ */
 const _objectChangeEvent = { type: 'objectChange' };
 
+/**
+ * This class can be used to transform objects in 3D space by adapting a similar interaction model
+ * of DCC tools like Blender. Unlike other controls, it is not intended to transform the scene's camera.
+ *
+ * `TransformControls` expects that its attached 3D object is part of the scene graph.
+ *
+ * @augments Controls
+ */
 class TransformControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Camera} camera - The camera of the rendered scene.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( camera, domElement = null ) {
 
 		super( undefined, domElement );
@@ -96,25 +138,170 @@ class TransformControls extends Controls {
 		// Setting the defined property will automatically trigger change event
 		// Defined properties are passed down to gizmo and plane
 
+		/**
+		 * The camera of the rendered scene.
+		 *
+		 * @name TransformControls#camera
+		 * @type {Camera}
+		 */
 		defineProperty( 'camera', camera );
 		defineProperty( 'object', undefined );
 		defineProperty( 'enabled', true );
+
+		/**
+		 * The current transformation axis.
+		 *
+		 * @name TransformControls#axis
+		 * @type {string}
+		 */
 		defineProperty( 'axis', null );
+
+		/**
+		 * The current transformation axis.
+		 *
+		 * @name TransformControls#mode
+		 * @type {('translate'|'rotate'|'scale')}
+		 * @default 'translate'
+		 */
 		defineProperty( 'mode', 'translate' );
+
+		/**
+		 * By default, 3D objects are continuously translated. If you set this property to a numeric
+		 * value (world units), you can define in which steps the 3D object should be translated.
+		 *
+		 * @name TransformControls#translationSnap
+		 * @type {?number}
+		 * @default null
+		 */
 		defineProperty( 'translationSnap', null );
+
+		/**
+		 * By default, 3D objects are continuously rotated. If you set this property to a numeric
+		 * value (radians), you can define in which steps the 3D object should be rotated.
+		 *
+		 * @name TransformControls#rotationSnap
+		 * @type {?number}
+		 * @default null
+		 */
 		defineProperty( 'rotationSnap', null );
+
+		/**
+		 * By default, 3D objects are continuously scaled. If you set this property to a numeric
+		 * value, you can define in which steps the 3D object should be scaled.
+		 *
+		 * @name TransformControls#scaleSnap
+		 * @type {?number}
+		 * @default null
+		 */
 		defineProperty( 'scaleSnap', null );
+
+		/**
+		 * Defines in which coordinate space transformations should be performed.
+		 *
+		 * @name TransformControls#space
+		 * @type {('world'|'local')}
+		 * @default 'world'
+		 */
 		defineProperty( 'space', 'world' );
+
+		/**
+		 * The size of the helper UI (axes/planes).
+		 *
+		 * @name TransformControls#size
+		 * @type {number}
+		 * @default 1
+		 */
 		defineProperty( 'size', 1 );
+
+		/**
+		 * Whether dragging is currently performed or not.
+		 *
+		 * @name TransformControls#dragging
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		defineProperty( 'dragging', false );
+
+		/**
+		 * Whether the x-axis helper should be visible or not.
+		 *
+		 * @name TransformControls#showX
+		 * @type {boolean}
+		 * @default true
+		 */
 		defineProperty( 'showX', true );
+
+		/**
+		 * Whether the y-axis helper should be visible or not.
+		 *
+		 * @name TransformControls#showY
+		 * @type {boolean}
+		 * @default true
+		 */
 		defineProperty( 'showY', true );
+
+		/**
+		 * Whether the z-axis helper should be visible or not.
+		 *
+		 * @name TransformControls#showZ
+		 * @type {boolean}
+		 * @default true
+		 */
 		defineProperty( 'showZ', true );
+
+		/**
+		 * The minimum allowed X position during translation.
+		 *
+		 * @name TransformControls#minX
+		 * @type {number}
+		 * @default -Infinity
+		 */
 		defineProperty( 'minX', - Infinity );
+
+		/**
+		 * The maximum allowed X position during translation.
+		 *
+		 * @name TransformControls#maxX
+		 * @type {number}
+		 * @default Infinity
+		 */
 		defineProperty( 'maxX', Infinity );
+
+		/**
+		 * The minimum allowed y position during translation.
+		 *
+		 * @name TransformControls#minY
+		 * @type {number}
+		 * @default -Infinity
+		 */
 		defineProperty( 'minY', - Infinity );
+
+		/**
+		 * The maximum allowed Y position during translation.
+		 *
+		 * @name TransformControls#maxY
+		 * @type {number}
+		 * @default Infinity
+		 */
 		defineProperty( 'maxY', Infinity );
+
+		/**
+		 * The minimum allowed z position during translation.
+		 *
+		 * @name TransformControls#minZ
+		 * @type {number}
+		 * @default -Infinity
+		 */
 		defineProperty( 'minZ', - Infinity );
+
+		/**
+		 * The maximum allowed Z position during translation.
+		 *
+		 * @name TransformControls#maxZ
+		 * @type {number}
+		 * @default Infinity
+		 */
 		defineProperty( 'maxZ', Infinity );
 
 		// Reusable utility variables
@@ -198,6 +385,12 @@ class TransformControls extends Controls {
 
 	}
 
+	/**
+	 * Returns the visual representation of the controls. Add the helper to your scene to
+	 * visually transform the attached  3D object.
+	 *
+	 * @return {TransformControlsRoot} The helper.
+	 */
 	getHelper() {
 
 		return this._root;
@@ -550,7 +743,12 @@ class TransformControls extends Controls {
 
 	}
 
-	// Set current object
+	/**
+	 * Sets the 3D object that should be transformed and ensures the controls UI is visible.
+	 *
+	 * @param {Object3D} object -  The 3D object that should be transformed.
+	 * @return {TransformControls} A reference to this controls.
+	 */
 	attach( object ) {
 
 		this.object = object;
@@ -560,7 +758,11 @@ class TransformControls extends Controls {
 
 	}
 
-	// Detach from object
+	/**
+	 * Removes the current 3D object from the controls and makes the helper UI invisible.
+	 *
+	 * @return {TransformControls} A reference to this controls.
+	 */
 	detach() {
 
 		this.object = undefined;
@@ -572,6 +774,9 @@ class TransformControls extends Controls {
 
 	}
 
+	/**
+	 * Resets the object's position, rotation and scale to when the current transform began.
+	 */
 	reset() {
 
 		if ( ! this.enabled ) return;
@@ -591,50 +796,89 @@ class TransformControls extends Controls {
 
 	}
 
+	/**
+	 * Returns the raycaster that is used for user interaction. This object is shared between all
+	 * instances of `TransformControls`.
+	 *
+	 * @returns {Raycaster} The internal raycaster.
+	 */
 	getRaycaster() {
 
 		return _raycaster;
 
 	}
 
-	// TODO: deprecate
-
+	/**
+	 * Returns the transformation mode.
+	 *
+	 * @returns {'translate'|'rotate'|'scale'} The transformation mode.
+	 */
 	getMode() {
 
 		return this.mode;
 
 	}
 
+	/**
+	 * Sets the given transformation mode.
+	 *
+	 * @param {'translate'|'rotate'|'scale'} mode - The transformation mode to set.
+	 */
 	setMode( mode ) {
 
 		this.mode = mode;
 
 	}
 
+	/**
+	 * Sets the translation snap.
+	 *
+	 * @param {?number} translationSnap - The translation snap to set.
+	 */
 	setTranslationSnap( translationSnap ) {
 
 		this.translationSnap = translationSnap;
 
 	}
 
+	/**
+	 * Sets the rotation snap.
+	 *
+	 * @param {?number} rotationSnap - The rotation snap to set.
+	 */
 	setRotationSnap( rotationSnap ) {
 
 		this.rotationSnap = rotationSnap;
 
 	}
 
+	/**
+	 * Sets the scale snap.
+	 *
+	 * @param {?number} scaleSnap - The scale snap to set.
+	 */
 	setScaleSnap( scaleSnap ) {
 
 		this.scaleSnap = scaleSnap;
 
 	}
 
+	/**
+	 * Sets the size of the helper UI.
+	 *
+	 * @param {number} size - The size to set.
+	 */
 	setSize( size ) {
 
 		this.size = size;
 
 	}
 
+	/**
+	 * Sets the coordinate space in which transformations are applied.
+	 *
+	 * @param {'world'|'local'} space - The space to set.
+	 */
 	setSpace( space ) {
 
 		this.space = space;

utils/docs/jsdoc.config.json

@@ -12,6 +12,9 @@
     "plugins": [ "plugins/markdown" ],
     "source": {
         "include": [
+            "examples/jsm/animation",
+            "examples/jsm/capabilities",
+            "examples/jsm/controls",
             "examples/jsm/tsl",
             "src"
         ],