Docs: improve Promise typing

Author: Samuel Rigaud

examples/jsm/exporters/GLTFExporter.js

@@ -304,8 +304,9 @@ const GLB_CHUNK_TYPE_BIN = 0x004E4942;
 
 /**
  * Compare two arrays
- * @param  {Array} array1 Array 1 to compare
- * @param  {Array} array2 Array 2 to compare
+ * @template {T}
+ * @param  {Array<T>} array1 Array 1 to compare
+ * @param  {Array<T>} array2 Array 2 to compare
  * @return {Boolean}        Returns true if both arrays are equal
  */
 function equalArray( array1, array2 ) {

src/nodes/code/ScriptableNode.js

@@ -416,7 +416,7 @@ class ScriptableNode extends Node {
 	 *
 	 * @param {String} name - The function name.
 	 * @param {...Any} params - A list of parameters.
-	 * @return {Any} The result of the function call.
+	 * @return {Promise<Any>} The result of the function call.
 	 */
 	async callAsync( name, ...params ) {
 

src/renderers/common/Backend.js

@@ -207,7 +207,7 @@ class Backend {
 	 *
 	 * @abstract
 	 * @param {RenderObject} renderObject - The render object.
-	 * @param {Array<Promise>} promises - An array of compilation promises which are used in `compileAsync()`.
+	 * @param {Array<Promise<void>>} promises - An array of compilation promises which are used in `compileAsync()`.
 	 */
 	createRenderPipeline( /*renderObject, promises*/ ) { }
 

src/renderers/common/Pipelines.js

@@ -343,7 +343,7 @@ class Pipelines extends DataMap {
 	 * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader.
 	 * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader.
 	 * @param {String} cacheKey - The cache key.
-	 * @param {Array} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
+	 * @param {Array<Promise<void>>?} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
 	 * @return {ComputePipeline} The compute pipeline.
 	 */
 	_getRenderPipeline( renderObject, stageVertex, stageFragment, cacheKey, promises ) {

src/renderers/common/PostProcessing.js

@@ -148,7 +148,7 @@ class PostProcessing {
 	 * its animation loop (not the one from the renderer).
 	 *
 	 * @async
-	 * @return {Promise} A Promise that resolves when the render has been finished.
+	 * @return {Promise<void>} A Promise that resolves when the render has been finished.
 	 */
 	async renderAsync() {
 

src/renderers/common/Renderer.js

@@ -691,7 +691,7 @@ class Renderer {
 	 * Initializes the renderer so it is ready for usage.
 	 *
 	 * @async
-	 * @return {Promise} A Promise that resolves when the renderer has been initialized.
+	 * @return {Promise<void>} A Promise that resolves when the renderer has been initialized.
 	 */
 	async init() {
 
@@ -795,7 +795,7 @@ class Renderer {
 	 * @param {Object3D} scene - The scene or 3D object to precompile.
 	 * @param {Camera} camera - The camera that is used to render the scene.
 	 * @param {Scene} targetScene - If the first argument is a 3D object, this parameter must represent the scene the 3D object is going to be added.
-	 * @return {Promise} A Promise that resolves when the compile has been finished.
+	 * @return {Promise<Array<void>>} A Promise that resolves when the compile has been finished.
 	 */
 	async compileAsync( scene, camera, targetScene = null ) {
 
@@ -927,7 +927,7 @@ class Renderer {
 	 * @async
 	 * @param {Object3D} scene - The scene or 3D object to render.
 	 * @param {Camera} camera - The camera.
-	 * @return {Promise} A Promise that resolves when the render has been finished.
+	 * @return {Promise<void>} A Promise that resolves when the render has been finished.
 	 */
 	async renderAsync( scene, camera ) {
 
@@ -944,7 +944,7 @@ class Renderer {
 	 * the CPU waits for the GPU to complete its operation (e.g. a compute task).
 	 *
 	 * @async
-	 * @return {Promise} A Promise that resolves when synchronization has been finished.
+	 * @return {Promise<void>} A Promise that resolves when synchronization has been finished.
 	 */
 	async waitForGPU() {
 
@@ -1433,7 +1433,7 @@ class Renderer {
 	 *
 	 * @async
 	 * @param {Function} callback - The application's animation loop.
-	 * @return {Promise} A Promise that resolves when the set has been executed.
+	 * @return {Promise<void>} A Promise that resolves when the set has been executed.
 	 */
 	async setAnimationLoop( callback ) {
 
@@ -1920,7 +1920,7 @@ class Renderer {
 	 * @param {Boolean} [color=true] - Whether the color buffer should be cleared or not.
 	 * @param {Boolean} [depth=true] - Whether the depth buffer should be cleared or not.
 	 * @param {Boolean} [stencil=true] - Whether the stencil buffer should be cleared or not.
-	 * @return {Promise} A Promise that resolves when the clear operation has been executed.
+	 * @return {Promise<void>} A Promise that resolves when the clear operation has been executed.
 	 */
 	async clearAsync( color = true, depth = true, stencil = true ) {
 
@@ -2187,7 +2187,7 @@ class Renderer {
 	 *
 	 * @async
 	 * @param {Node|Array<Node>} computeNodes - The compute node(s).
-	 * @return {Promise?} A Promise that resolve when the compute has finished.
+	 * @return {Promise<void>} A Promise that resolve when the compute has finished.
 	 */
 	async computeAsync( computeNodes ) {
 
@@ -2252,7 +2252,7 @@ class Renderer {
 	 *
 	 * @async
 	 * @param {Texture} texture - The texture.
-	 * @return {Promise} A Promise that resolves when the texture has been initialized.
+	 * @return {Promise<void>} A Promise that resolves when the texture has been initialized.
 	 */
 	async initTextureAsync( texture ) {
 

src/renderers/common/extras/PMREMGenerator.js

@@ -135,6 +135,7 @@ class PMREMGenerator {
 	 * @param {Number} [far=100] - The far plane distance.
 	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
 	 * @return {RenderTarget} The resulting PMREM.
+	 * @see fromSceneAsync
 	 */
 	fromScene( scene, sigma = 0, near = 0.1, far = 100, renderTarget = null ) {
 
@@ -175,6 +176,21 @@ class PMREMGenerator {
 
 	}
 
+	/**
+	 * Generates a PMREM from a supplied Scene, which can be faster than using an
+	 * image if networking bandwidth is low. Optional sigma specifies a blur radius
+	 * in radians to be applied to the scene before PMREM generation. Optional near
+	 * and far planes ensure the scene is rendered in its entirety (the cubeCamera
+	 * is placed at the origin).
+	 *
+	 * @param {Scene} scene - The scene to be captured.
+	 * @param {Number} [sigma=0] - The blur radius in radians.
+	 * @param {Number} [near=0.1] - The near plane distance.
+	 * @param {Number} [far=100] - The far plane distance.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {Promise<RenderTarget>} The resulting PMREM.
+	 * @see fromScene
+	 */
 	async fromSceneAsync( scene, sigma = 0, near = 0.1, far = 100, renderTarget = null ) {
 
 		if ( this._hasInitialized === false ) await this._renderer.init();
@@ -191,6 +207,7 @@ class PMREMGenerator {
 	 * @param {Texture} equirectangular - The equirectangular texture to be converted.
 	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
 	 * @return {RenderTarget} The resulting PMREM.
+	 * @see fromEquirectangularAsync
 	 */
 	fromEquirectangular( equirectangular, renderTarget = null ) {
 
@@ -212,6 +229,16 @@ class PMREMGenerator {
 
 	}
 
+	/**
+	 * Generates a PMREM from an equirectangular texture, which can be either LDR
+	 * or HDR. The ideal input image size is 1k (1024 x 512),
+	 * as this matches best with the 256 x 256 cubemap output.
+	 *
+	 * @param {Texture} equirectangular - The equirectangular texture to be converted.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {Promise<RenderTarget>} The resulting PMREM.
+	 * @see fromEquirectangular
+	 */
 	async fromEquirectangularAsync( equirectangular, renderTarget = null ) {
 
 		if ( this._hasInitialized === false ) await this._renderer.init();
@@ -228,6 +255,7 @@ class PMREMGenerator {
 	 * @param {Texture} cubemap - The cubemap texture to be converted.
 	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
 	 * @return {RenderTarget} The resulting PMREM.
+	 * @see fromCubemapAsync
 	 */
 	fromCubemap( cubemap, renderTarget = null ) {
 
@@ -249,6 +277,16 @@ class PMREMGenerator {
 
 	}
 
+	/**
+	 * Generates a PMREM from an cubemap texture, which can be either LDR
+	 * or HDR. The ideal input cube size is 256 x 256,
+	 * with the 256 x 256 cubemap output.
+	 *
+	 * @param {Texture} cubemap - The cubemap texture to be converted.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {Promise<RenderTarget>} The resulting PMREM.
+	 * @see fromCubemap
+	 */
 	async fromCubemapAsync( cubemap, renderTarget = null ) {
 
 		if ( this._hasInitialized === false ) await this._renderer.init();
@@ -260,6 +298,8 @@ class PMREMGenerator {
 	/**
 	 * Pre-compiles the cubemap shader. You can get faster start-up by invoking this method during
 	 * your texture's network fetch for increased concurrency.
+	 *
+	 * @returns {Promise<void>}
 	 */
 	async compileCubemapShader() {
 
@@ -275,6 +315,8 @@ class PMREMGenerator {
 	/**
 	 * Pre-compiles the equirectangular shader. You can get faster start-up by invoking this method during
 	 * your texture's network fetch for increased concurrency.
+	 *
+	 * @returns {Promise<void>}
 	 */
 	async compileEquirectangularShader() {
 

src/renderers/webgl-fallback/WebGLBackend.js

@@ -276,7 +276,7 @@ class WebGLBackend extends Backend {
 	 * the CPU waits for the GPU to complete its operation (e.g. a compute task).
 	 *
 	 * @async
-	 * @return {Promise} A Promise that resolves when synchronization has been finished.
+	 * @return {Promise<void>} A Promise that resolves when synchronization has been finished.
 	 */
 	async waitForGPU() {
 
@@ -1247,7 +1247,7 @@ class WebGLBackend extends Backend {
 	 * Creates a render pipeline for the given render object.
 	 *
 	 * @param {RenderObject} renderObject - The render object.
-	 * @param {Array<Promise>} promises - An array of compilation promises which are used in `compileAsync()`.
+	 * @param {Array<Promise<void>>} promises - An array of compilation promises which are used in `compileAsync()`.
 	 */
 	createRenderPipeline( renderObject, promises ) {
 

src/renderers/webgpu/WebGPUBackend.js

@@ -150,7 +150,7 @@ class WebGPUBackend extends Backend {
 	 *
 	 * @async
 	 * @param {Renderer} renderer - The renderer.
-	 * @return {Promise} A Promise that resolves when the backend has been initialized.
+	 * @return {Promise<void>} A Promise that resolves when the backend has been initialized.
 	 */
 	async init( renderer ) {
 
@@ -764,6 +764,7 @@ class WebGPUBackend extends Backend {
 	 *
 	 * @async
 	 * @param {RenderContext} renderContext - The render context.
+	 * @return {Promise<void>} A Promise that resolves when the occlusion query results have been processed.
 	 */
 	async resolveOccludedAsync( renderContext ) {
 
@@ -1063,7 +1064,7 @@ class WebGPUBackend extends Backend {
 	 * the CPU waits for the GPU to complete its operation (e.g. a compute task).
 	 *
 	 * @async
-	 * @return {Promise} A Promise that resolves when synchronization has been finished.
+	 * @return {Promise<void>} A Promise that resolves when synchronization has been finished.
 	 */
 	async waitForGPU() {
 
@@ -1539,7 +1540,7 @@ class WebGPUBackend extends Backend {
 	 * @async
 	 * @param {RenderContext} renderContext - The render context.
 	 * @param {String} type - The render context.
-	 * @return {Promise} A Promise that resolves when the time stamp has been computed.
+	 * @return {Promise<void>} A Promise that resolves when the time stamp has been computed.
 	 */
 	async resolveTimestampAsync( renderContext, type = 'render' ) {
 
@@ -1617,7 +1618,7 @@ class WebGPUBackend extends Backend {
 	 * Creates a render pipeline for the given render object.
 	 *
 	 * @param {RenderObject} renderObject - The render object.
-	 * @param {Array<Promise>} promises - An array of compilation promises which are used in `compileAsync()`.
+	 * @param {Array<Promise<void>>} promises - An array of compilation promises which are used in `compileAsync()`.
 	 */
 	createRenderPipeline( renderObject, promises ) {
 

src/renderers/webgpu/utils/WebGPUPipelineUtils.js

@@ -55,7 +55,7 @@ class WebGPUPipelineUtils {
 	 * Creates a render pipeline for the given render object.
 	 *
 	 * @param {RenderObject} renderObject - The render object.
-	 * @param {Array<Promise>} promises - An array of compilation promises which are used in `compileAsync()`.
+	 * @param {Array<Promise<void>>} promises - An array of compilation promises which are used in `compileAsync()`.
 	 */
 	createRenderPipeline( renderObject, promises ) {