Docs: improve Jsdoc types (#30603)

Co-authored-by: Samuel Rigaud <srigaud@duodisplay.com>

src/audio/Audio.js

@@ -308,7 +308,7 @@ class Audio extends Object3D {
 	 * Can only be used with compatible audio sources that allow playback control.
 	 *
 	 * @param {number} [delay=0] - The delay, in seconds, at which the audio should start playing.
-	 * @return {Audio} A reference to this instance.
+	 * @return {Audio|undefined} A reference to this instance.
 	 */
 	play( delay = 0 ) {
 
@@ -352,7 +352,7 @@ class Audio extends Object3D {
 	 *
 	 * Can only be used with compatible audio sources that allow playback control.
 	 *
-	 * @return {Audio} A reference to this instance.
+	 * @return {Audio|undefined} A reference to this instance.
 	 */
 	pause() {
 
@@ -394,7 +394,7 @@ class Audio extends Object3D {
 	 * Can only be used with compatible audio sources that allow playback control.
 	 *
 	 * @param {number} [delay=0] - The delay, in seconds, at which the audio should stop playing.
-	 * @return {Audio} A reference to this instance.
+	 * @return {Audio|undefined} A reference to this instance.
 	 */
 	stop( delay = 0 ) {
 
@@ -456,7 +456,7 @@ class Audio extends Object3D {
 	 * Disconnects to the audio source. This is used internally on
 	 * initialisation and when setting / removing filters.
 	 *
-	 * @return {Audio} A reference to this instance.
+	 * @return {Audio|undefined} A reference to this instance.
 	 */
 	disconnect() {
 
@@ -587,7 +587,7 @@ class Audio extends Object3D {
 	 * Can only be used with compatible audio sources that allow playback control.
 	 *
 	 * @param {number} [value] - The playback rate to set.
-	 * @return {Audio} A reference to this instance.
+	 * @return {Audio|undefined} A reference to this instance.
 	 */
 	setPlaybackRate( value ) {
 
@@ -657,7 +657,7 @@ class Audio extends Object3D {
 	 * Can only be used with compatible audio sources that allow playback control.
 	 *
 	 * @param {boolean} value - Whether the audio should loop or not.
-	 * @return {Audio} A reference to this instance.
+	 * @return {Audio|undefined} A reference to this instance.
 	 */
 	setLoop( value ) {
 

src/extras/PMREMGenerator.js

@@ -108,7 +108,7 @@ class PMREMGenerator {
 	 * @param {number} sigma
 	 * @param {number} near
 	 * @param {number} far
-	 * @param {?Object} [options={}]
+	 * @param {Object} [options={}]
 	 * @return {WebGLRenderTarget}
 	 */
 	fromScene( scene, sigma = 0, near = 0.1, far = 100, options = {} ) {
@@ -152,7 +152,7 @@ class PMREMGenerator {
 	 * The smallest supported equirectangular image size is 64 x 32.
 	 *
 	 * @param {Texture} equirectangular
-	 * @param {WebGLRenderTarget} [renderTarget=null] - Optional render target.
+	 * @param {?WebGLRenderTarget} [renderTarget=null] - Optional render target.
 	 * @return {WebGLRenderTarget}
 	 */
 	fromEquirectangular( equirectangular, renderTarget = null ) {

src/extras/core/Path.js

@@ -264,7 +264,7 @@ class Path extends CurvePath {
 	 * @param {number} aStartAngle - The start angle in radians.
 	 * @param {number} aEndAngle - The end angle in radians.
 	 * @param {boolean} [aClockwise=false] - Whether to sweep the ellipse clockwise or not.
-	 * @param {boolean} [aRotation=0] - The rotation angle of the ellipse in radians, counterclockwise from the positive X axis.
+	 * @param {number} [aRotation=0] - The rotation angle of the ellipse in radians, counterclockwise from the positive X axis.
 	 * @return {Path} A reference to this path.
 	 */
 	absellipse( aX, aY, xRadius, yRadius, aStartAngle, aEndAngle, aClockwise, aRotation ) {

src/materials/nodes/NodeMaterial.js

@@ -257,7 +257,7 @@ class NodeMaterial extends Material {
 		 * simulation would be implemented as compute shaders and managed inside a `Fn` function. This function is
 		 * eventually assigned to `geometryNode`.
 		 *
-		 * @type {Function}
+		 * @type {?Function}
 		 * @default null
 		 */
 		this.geometryNode = null;

src/math/Color.js

@@ -561,7 +561,7 @@ class Color {
 	 *
 	 * @param {{h:0,s:0,l:0}} target - The target object that is used to store the method's result.
 	 * @param {string} [colorSpace=ColorManagement.workingColorSpace] - The color space.
-	 * @return {{h:0,s:0,l:0}} The HSL representation of this color.
+	 * @return {{h:number,s:number,l:number}} The HSL representation of this color.
 	 */
 	getHSL( target, colorSpace = ColorManagement.workingColorSpace ) {
 

src/math/Line3.js

@@ -91,7 +91,7 @@ class Line3 {
 	/**
 	 * Returns the squared Euclidean distance between the line' start and end point.
 	 *
-	 * @return {Vector3} The squared Euclidean distance.
+	 * @return {number} The squared Euclidean distance.
 	 */
 	distanceSq() {
 
@@ -102,7 +102,7 @@ class Line3 {
 	/**
 	 * Returns the Euclidean distance between the line' start and end point.
 	 *
-	 * @return {Vector3} The Euclidean distance.
+	 * @return {number} The Euclidean distance.
 	 */
 	distance() {
 
@@ -113,7 +113,7 @@ class Line3 {
 	/**
 	 * Returns a vector at a certain position along the line segment.
 	 *
-	 * @param {Vector3} t - A value between `[0,1]` to represent a position along the line segment.
+	 * @param {number} t - A value between `[0,1]` to represent a position along the line segment.
 	 * @param {Vector3} target - The target vector that is used to store the method's result.
 	 * @return {Vector3} The delta vector.
 	 */

src/math/Plane.js

@@ -290,7 +290,7 @@ class Plane {
 	 * projection of the normal at the origin onto the plane.
 	 *
 	 * @param {Vector3} target - The target vector that is used to store the method's result.
-	 * @return {boolean} The coplanar point.
+	 * @return {Vector3} The coplanar point.
 	 */
 	coplanarPoint( target ) {
 

src/math/Vector2.js

@@ -579,7 +579,7 @@ class Vector2 {
 	 * Calculates the cross product of the given vector with this instance.
 	 *
 	 * @param {Vector2} v - The vector to compute the cross product with.
-	 * @return {Vector2} The result of the cross product.
+	 * @return {number} The result of the cross product.
 	 */
 	cross( v ) {
 

src/math/Vector3.js

@@ -267,7 +267,7 @@ class Vector3 {
 	/**
 	 * Adds the given vector scaled by the given factor to this instance.
 	 *
-	 * @param {Vector3} v - The vector.
+	 * @param {Vector3|Vector4} v - The vector.
 	 * @param {number} s - The factor that scales `v`.
 	 * @return {Vector3} A reference to this vector.
 	 */

src/nodes/core/NodeUtils.js

@@ -77,7 +77,7 @@ export const hash = ( ...params ) => cyrb53( params );
  * Computes a cache key for the given node.
  *
  * @method
- * @param {Object} object - The object to be hashed.
+ * @param {Object|Node} object - The object to be hashed.
  * @param {boolean} [force=false] - Whether to force a cache key computation or not.
  * @return {number} The hash.
  */

src/renderers/common/extras/PMREMGenerator.js

@@ -202,7 +202,7 @@ class PMREMGenerator {
 	 * @param {number} [far=100] - The far plane distance.
 	 * @param {Object} [options={}] - The configuration options.
 	 * @param {number} [options.size=256] - The texture size of the PMREM.
-	 * @param {Vector3} [options.renderTarget=origin] - The position of the internal cube camera that renders the scene.
+	 * @param {Vector3} [options.position=origin] - The position of the internal cube camera that renders the scene.
 	 * @param {?RenderTarget} [options.renderTarget=null] - The render target to use.
 	 * @return {Promise<RenderTarget>} A Promise that resolve with the PMREM when the generation has been finished.
 	 * @see {@link PMREMGenerator#fromScene}

src/renderers/webgpu/utils/WebGPUTexturePassUtils.js

@@ -343,7 +343,7 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 	 * @param {GPUTexture} textureGPU - The GPU texture object.
 	 * @param {Object} textureGPUDescriptor - The texture descriptor.
 	 * @param {number} baseArrayLayer - The index of the first array layer accessible to the texture view.
-	 * @return {Array} An array of render bundles.
+	 * @return {Array<Object>} An array of render bundles.
 	 */
 	_mipmapCreateBundles( textureGPU, textureGPUDescriptor, baseArrayLayer ) {
 
@@ -414,7 +414,7 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 	 * Executes the render bundles.
 	 *
 	 * @param {GPUCommandEncoder} commandEncoder - The GPU command encoder.
-	 * @param {Array} passes - An array of render bundles.
+	 * @param {Array<Object>} passes - An array of render bundles.
 	 */
 	_mipmapRunBundles( commandEncoder, passes ) {
 

src/renderers/webgpu/utils/WebGPUTextureUtils.js

@@ -178,7 +178,6 @@ class WebGPUTextureUtils {
 	 *
 	 * @param {Texture} texture - The texture.
 	 * @param {Object} [options={}] - Optional configuration parameter.
-	 * @return {undefined}
 	 */
 	createTexture( texture, options = {} ) {
 
@@ -266,7 +265,8 @@ class WebGPUTextureUtils {
 
 				console.warn( 'WebGPURenderer: Texture format not supported.' );
 
-				return this.createDefaultTexture( texture );
+				this.createDefaultTexture( texture );
+				return;
 
 			}