JSDoc: Add @deprecated (#30284)

* JSDoc: Add @deprecated * Update TSLCore.js --------- Co-authored-by: Samuel Rigaud <srigaud@duodisplay.com> Co-authored-by: Michael Herzog <michael.herzog@human-interactive.org>
mrdoob · Jan 9, 2025 · ee4bdac · ee4bdac
1 parent 1b5a3bb
commit ee4bdac
Show file tree

Hide file tree

Showing 15 changed files with 160 additions and 7 deletions.
diff --git a/src/nodes/accessors/StorageBufferNode.js b/src/nodes/accessors/StorageBufferNode.js
@@ -344,6 +344,15 @@ export default StorageBufferNode;
  */
 export const storage = ( value, type = null, count = 0 ) => nodeObject( new StorageBufferNode( value, type, count ) );
 
+/**
+ * @function
+ * @deprecated since r171. Use `storage().setPBO( true )` instead.
+ *
+ * @param {StorageBufferAttribute|StorageInstancedBufferAttribute|BufferAttribute} value - The buffer data.
+ * @param {String?} type - The buffer type (e.g. `'vec3'`).
+ * @param {Number} count - The buffer count.
+ * @returns {StorageBufferNode}
+ */
 export const storageObject = ( value, type, count ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "storageObject()" is deprecated. Use "storage().setPBO( true )" instead.' );

diff --git a/src/nodes/accessors/TextureNode.js b/src/nodes/accessors/TextureNode.js
@@ -521,6 +521,13 @@ class TextureNode extends UniformNode {
 
 	// @TODO: Move to TSL
 
+	/**
+	 * @function
+	 * @deprecated since r172. Use {@link TextureNode#sample} instead.
+	 *
+	 * @param {Node} uvNode - The uv node.
+	 * @return {TextureNode} A texture node representing the texture sample.
+	 */
 	uv( uvNode ) { // @deprecated, r172
 
 		console.warn( 'THREE.TextureNode: .uv() has been renamed. Use .sample() instead.' );

diff --git a/src/nodes/accessors/UniformArrayNode.js b/src/nodes/accessors/UniformArrayNode.js
@@ -348,8 +348,14 @@ export default UniformArrayNode;
  */
 export const uniformArray = ( values, nodeType ) => nodeObject( new UniformArrayNode( values, nodeType ) );
 
-//
-
+/**
+ * @function
+ * @deprecated since r168. Use {@link uniformArray} instead.
+ *
+ * @param {Array<Any>} values - Array-like data.
+ * @param {String} nodeType - The data type of the array elements.
+ * @returns {UniformArrayNode}
+ */
 export const uniforms = ( values, nodeType ) => { // @deprecated, r168
 
 	console.warn( 'TSL.UniformArrayNode: uniforms() has been renamed to uniformArray().' );

diff --git a/src/nodes/core/NodeBuilder.js b/src/nodes/core/NodeBuilder.js
@@ -2469,6 +2469,13 @@ class NodeBuilder {
 
 	// deprecated
 
+	/**
+	 * @function
+	 * @deprecated since r168. Use `new NodeMaterial()` instead, with targeted node material name.
+	 *
+	 * @param {String} [type='NodeMaterial'] - The node material type.
+	 * @throws {Error}
+	 */
 	createNodeMaterial( type = 'NodeMaterial' ) { // @deprecated, r168
 
 		throw new Error( `THREE.NodeBuilder: createNodeMaterial() was deprecated. Use new ${ type }() instead.` );

diff --git a/src/nodes/core/StackNode.js b/src/nodes/core/StackNode.js
@@ -157,15 +157,28 @@ class StackNode extends Node {
 
 	}
 
-	//
+	// deprecated
 
+	/**
+	 * @function
+	 * @deprecated since r168. Use {@link StackNode#Else} instead.
+	 *
+	 * @param  {...any} params
+	 * @returns {StackNode}
+	 */
 	else( ...params ) { // @deprecated, r168
 
 		console.warn( 'TSL.StackNode: .else() has been renamed to .Else().' );
 		return this.Else( ...params );
 
 	}
 
+	/**
+	 * @deprecated since r168. Use {@link StackNode#ElseIf} instead.
+	 *
+	 * @param  {...any} params
+	 * @returns {StackNode}
+	 */
 	elseif( ...params ) { // @deprecated, r168
 
 		console.warn( 'TSL.StackNode: .elseif() has been renamed to .ElseIf().' );

diff --git a/src/nodes/core/VarNode.js b/src/nodes/core/VarNode.js
@@ -180,6 +180,13 @@ addMethodChaining( 'toConst', Const );
 
 // Deprecated
 
+/**
+ * @function
+ * @deprecated since r170. Use `Var( node )` or `node.toVar()` instead.
+ *
+ * @param {Any} node
+ * @returns {VarNode}
+ */
 export const temp = ( node ) => { // @deprecated, r170
 
 	console.warn( 'TSL: "temp( node )" is deprecated. Use "Var( node )" or "node.toVar()" instead.' );

diff --git a/src/nodes/display/BlendModes.js b/src/nodes/display/BlendModes.js
@@ -70,27 +70,55 @@ export const blendColor = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 
 // deprecated
 
+/**
+ * @function
+ * @deprecated since r171. Use {@link blendBurn} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const burn = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "burn" has been renamed. Use "blendBurn" instead.' );
 	return blendBurn( params );
 
 };
 
+/**
+ * @function
+ * @deprecated since r171. Use {@link blendDodge} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const dodge = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "dodge" has been renamed. Use "blendDodge" instead.' );
 	return blendDodge( params );
 
 };
 
+/**
+ * @function
+ * @deprecated since r171. Use {@link blendScreen} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const screen = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "screen" has been renamed. Use "blendScreen" instead.' );
 	return blendScreen( params );
 
 };
 
+/**
+ * @function
+ * @deprecated since r171. Use {@link blendOverlay} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const overlay = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "overlay" has been renamed. Use "blendOverlay" instead.' );

diff --git a/src/nodes/display/ScreenNode.js b/src/nodes/display/ScreenNode.js
@@ -243,6 +243,9 @@ export const viewportUV = /*@__PURE__*/ viewportCoordinate.div( viewportSize );
 
 // Deprecated
 
+/**
+ * @deprecated since r169. Use {@link screenSize} instead.
+ */
 export const viewportResolution = /*@__PURE__*/ ( Fn( () => { // @deprecated, r169
 
 	console.warn( 'TSL.ViewportNode: "viewportResolution" is deprecated. Use "screenSize" instead.' );
@@ -251,6 +254,9 @@ export const viewportResolution = /*@__PURE__*/ ( Fn( () => { // @deprecated, r1
 
 }, 'vec2' ).once() )();
 
+/**
+ * @deprecated since r168. Use {@link screenUV} instead.
+ */
 export const viewportTopLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
 	console.warn( 'TSL.ViewportNode: "viewportTopLeft" is deprecated. Use "screenUV" instead.' );
@@ -259,6 +265,9 @@ export const viewportTopLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
 }, 'vec2' ).once() )();
 
+/**
+ * @deprecated since r168. Use `screenUV.flipY()` instead.
+ */
 export const viewportBottomLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
 	console.warn( 'TSL.ViewportNode: "viewportBottomLeft" is deprecated. Use "screenUV.flipY()" instead.' );

diff --git a/src/nodes/fog/Fog.js b/src/nodes/fog/Fog.js
@@ -78,13 +78,30 @@ export const fog = Fn( ( [ color, factor ] ) => {
 
 // Deprecated
 
+/**
+ * @function
+ * @deprecated since r171. Use `fog( color, rangeFogFactor( near, far ) )` instead.
+ *
+ * @param {Node} color
+ * @param {Node} near
+ * @param {Node} far
+ * @returns {Function}
+ */
 export function rangeFog( color, near, far ) { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "rangeFog( color, near, far )" is deprecated. Use "fog( color, rangeFogFactor( near, far ) )" instead.' );
 	return fog( color, rangeFogFactor( near, far ) );
 
 }
 
+/**
+ * @function
+ * @deprecated since r171. Use `fog( color, densityFogFactor( density ) )` instead.
+ *
+ * @param {Node} color
+ * @param {Node} density
+ * @returns {Function}
+ */
 export function densityFog( color, density ) { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "densityFog( color, density )" is deprecated. Use "fog( color, densityFogFactor( density ) )" instead.' );

diff --git a/src/nodes/math/ConditionalNode.js b/src/nodes/math/ConditionalNode.js
@@ -211,8 +211,15 @@ export const select = /*@__PURE__*/ nodeProxy( ConditionalNode );
 
 addMethodChaining( 'select', select );
 
-//
+// deprecated
 
+/**
+ * @function
+ * @deprecated since r168. Use {@link select} instead.
+ *
+ * @param  {...any} params
+ * @returns {ConditionalNode}
+ */
 export const cond = ( ...params ) => { // @deprecated, r168
 
 	console.warn( 'TSL.ConditionalNode: cond() has been renamed to select().' );

diff --git a/src/nodes/math/MathNode.js b/src/nodes/math/MathNode.js
@@ -943,6 +943,8 @@ export const smoothstepElement = ( x, low, high ) => smoothstep( low, high, x );
  * Returns the arc-tangent of the quotient of its parameters.
  *
  * @function
+ * @deprecated since r172. Use {@link atan} instead.
+ *
  * @param {Node | Number} y - The y parameter.
  * @param {Node | Number} x - The x parameter.
  * @returns {Node}

diff --git a/src/nodes/math/OperatorNode.js b/src/nodes/math/OperatorNode.js
@@ -550,7 +550,13 @@ addMethodChaining( 'bitXor', bitXor );
 addMethodChaining( 'shiftLeft', shiftLeft );
 addMethodChaining( 'shiftRight', shiftRight );
 
-
+/**
+ * @function
+ * @deprecated since r168. Use {@link modInt} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const remainder = ( ...params ) => { // @deprecated, r168
 
 	console.warn( 'TSL.OperatorNode: .remainder() has been renamed to .modInt().' );

diff --git a/src/nodes/tsl/TSLCore.js b/src/nodes/tsl/TSLCore.js
@@ -8,7 +8,7 @@ import FlipNode from '../utils/FlipNode.js';
 import ConstNode from '../core/ConstNode.js';
 import { getValueFromType, getValueType } from '../core/NodeUtils.js';
 
-//
+/** @module TSLCore **/
 
 let currentStack = null;
 
@@ -553,6 +553,13 @@ export const Fn = ( jsFunc, nodeType ) => {
 
 };
 
+/**
+ * @function
+ * @deprecated since r168. Use {@link Fn} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const tslFn = ( ...params ) => { // @deprecated, r168
 
 	console.warn( 'TSL.ShaderNode: tslFn() has been renamed to Fn().' );

diff --git a/src/nodes/utils/LoopNode.js b/src/nodes/utils/LoopNode.js
@@ -274,8 +274,15 @@ export const Continue = () => expression( 'continue' ).append();
  */
 export const Break = () => expression( 'break' ).append();
 
-//
+// deprecated
 
+/**
+ * @function
+ * @deprecated since r168. Use {@link Loop} instead.
+ *
+ * @param  {...any} params
+ * @returns {LoopNode}
+ */
 export const loop = ( ...params ) => { // @deprecated, r168
 
 	console.warn( 'TSL.LoopNode: loop() has been renamed to Loop().' );

diff --git a/src/nodes/utils/Timer.js b/src/nodes/utils/Timer.js
@@ -26,20 +26,41 @@ export const frameId = /*@__PURE__*/ uniform( 0, 'uint' ).setGroup( renderGroup
 
 // Deprecated
 
+/**
+ * @function
+ * @deprecated since r170. Use {@link time} instead.
+ *
+ * @param {Number} [timeScale=1] - The time scale.
+ * @returns {UniformNode<float>}
+ */
 export const timerLocal = ( timeScale = 1 ) => { // @deprecated, r170
 
 	console.warn( 'TSL: timerLocal() is deprecated. Use "time" instead.' );
 	return time.mul( timeScale );
 
 };
 
+/**
+ * @function
+ * @deprecated since r170. Use {@link time} instead.
+ *
+ * @param {Number} [timeScale=1] - The time scale.
+ * @returns {UniformNode<float>}
+ */
 export const timerGlobal = ( timeScale = 1 ) => { // @deprecated, r170
 
 	console.warn( 'TSL: timerGlobal() is deprecated. Use "time" instead.' );
 	return time.mul( timeScale );
 
 };
 
+/**
+ * @function
+ * @deprecated since r170. Use {@link deltaTime} instead.
+ *
+ * @param {Number} [timeScale=1] - The time scale.
+ * @returns {UniformNode<float>}
+ */
 export const timerDelta = ( timeScale = 1 ) => { // @deprecated, r170
 
 	console.warn( 'TSL: timerDelta() is deprecated. Use "deltaTime" instead.' );