NodeBuilder: More docs. (#30038)

* more docs

* Update StackNode.js

---------

Co-authored-by: Michael Herzog <michael.herzog@human-interactive.org>

src/nodes/core/NodeBuilder.js

@@ -232,14 +232,14 @@ class NodeBuilder {
 		this.computeShader = null;
 
 		/**
-		 * TODO
+		 * Nodes used in the primary flow of code generation.
 		 *
-		 * @type {Object}
+		 * @type {Object<String,Array<Node>>}
 		 */
 		this.flowNodes = { vertex: [], fragment: [], compute: [] };
 
 		/**
-		 * TODO
+		 * Nodes code from `.flowNodes`.
 		 *
 		 * @type {Object<String,String>}
 		 */
@@ -322,7 +322,8 @@ class NodeBuilder {
 		this.vars = {};
 
 		/**
-		 * TODO
+		 * Current code flow.
+		 * All code generated in this stack will be stored in `.flow`.
 		 *
 		 * @type {{code: String}}
 		 */
@@ -330,8 +331,7 @@ class NodeBuilder {
 
 		/**
 		 * A chain of nodes.
-		 *
-		 * TODO: Explains purpose of this property.
+		 * Used to check recursive calls in node-graph.
 		 *
 		 * @type {Array<Node>}
 		 */
@@ -339,8 +339,8 @@ class NodeBuilder {
 
 		/**
 		 * The current stack.
-		 *
-		 * TODO: Explains purpose of this property.
+		 * This reflects the current process in the code block hierarchy,
+		 * it is useful to know if the current process is inside a conditional for example.
 		 *
 		 * @type {StackNode}
 		 */
@@ -348,8 +348,7 @@ class NodeBuilder {
 
 		/**
 		 * List of stack nodes.
-		 *
-		 * TODO: Explains purpose of this property.
+		 * The current stack hierarchy is stored in an array.
 		 *
 		 * @type {Array<StackNode>}
 		 */
@@ -580,9 +579,7 @@ class NodeBuilder {
 	}
 
 	/**
-	 * Returns a list bindings.
-	 *
-	 * TODO: Add more details.
+	 * Returns a list bindings of all shader stages separated by groups.
 	 *
 	 * @return {Array<BindGroup>} The list of bindings.
 	 */
@@ -679,7 +676,8 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO: Describe the difference to `addNode()`.
+	 * It is used to add Nodes that will be used as FRAME and RENDER events,
+	 * and need to follow a certain sequence in the calls to work correctly.
 	 *
 	 * @param {Node} node - The node to add.
 	 */
@@ -758,8 +756,7 @@ class NodeBuilder {
 
 	/**
 	 * Adds the given node to the internal node chain.
-	 *
-	 * TODO: Describe the difference to `addNode()`.
+	 * This is used to check recursive calls in node-graph.
 	 *
 	 * @param {Node} node - The node to add.
 	 */
@@ -822,11 +819,11 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Adds the Node to a target flow so that it can generate code in the 'generate' process.
 	 *
 	 * @param {('vertex'|'fragment'|'compute')} shaderStage - The shader stage.
-	 * @param {Node} node - The node.
-	 * @return {Node} The node
+	 * @param {Node} node - The node to add.
+	 * @return {Node} The node.
 	 */
 	addFlow( shaderStage, node ) {
 
@@ -859,9 +856,10 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Gets a context used in shader construction that can be shared across different materials.
+	 * This is necessary since the renderer cache can reuse shaders generated in one material and use them in another.
 	 *
-	 * @return {Object} TODO.
+	 * @return {Object} The builder's current context without material.
 	 */
 	getSharedContext() {
 
@@ -1686,10 +1684,13 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Adds a code flow based on the code-block hierarchy.
+
+	 * This is used so that code-blocks like If,Else create their variables locally if the Node
+	 * is only used inside one of these conditionals in the current shader stage.
 	 *
-	 * @param {Node} node - TODO.
-	 * @param {Node} nodeBlock - TODO.
+	 * @param {Node} node - The node to add.
+	 * @param {Node} nodeBlock - Node-based code-block. Usually 'ConditionalNode'.
 	 */
 	addFlowCodeHierarchy( node, nodeBlock ) {
 
@@ -1724,11 +1725,11 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Add a inline-code to the current flow code-block.
 	 *
-	 * @param {Node} node - TODO.
-	 * @param {String} code - TODO.
-	 * @param {Node} nodeBlock - TODO.
+	 * @param {Node} node - The node to add.
+	 * @param {String} code - The code to add.
+	 * @param {Node} nodeBlock - Current ConditionalNode
 	 */
 	addLineFlowCodeBlock( node, code, nodeBlock ) {
 
@@ -1742,10 +1743,10 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Add a inline-code to the current flow.
 	 *
-	 * @param {String} code - TODO.
-	 * @param {Node?} [node= null] - TODO.
+	 * @param {String} code - The code to add.
+	 * @param {Node?} [node= null] - Optional Node, can help the system understand if the Node is part of a code-block.
 	 * @return {NodeBuilder} A reference to this node builder.
 	 */
 	addLineFlowCode( code, node = null ) {
@@ -1773,9 +1774,9 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Adds a code to the current code flow.
 	 *
-	 * @param {String} code - TODO.
+	 * @param {String} code - Shader code.
 	 * @return {NodeBuilder} A reference to this node builder.
 	 */
 	addFlowCode( code ) {
@@ -1787,7 +1788,8 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Add tab in the code that will be generated so that other snippets respect the current tabulation.
+	 * Typically used in codes with If,Else.
 	 *
 	 * @return {NodeBuilder} A reference to this node builder.
 	 */
@@ -1800,7 +1802,7 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Removes a tab.
 	 *
 	 * @return {NodeBuilder} A reference to this node builder.
 	 */
@@ -1813,9 +1815,9 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Gets the current flow data based on a Node.
 	 *
-	 * @param {Node} node - TODO.
+	 * @param {Node} node - Node that the flow was started.
 	 * @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
 	 * @return {Object}
 	 */
@@ -1826,9 +1828,9 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Executes the node flow based on a root node to generate the final shader code.
 	 *
-	 * @param {Node} node - TODO.
+	 * @param {Node} node - The node to execute.
 	 * @return {Object}
 	 */
 	flowNode( node ) {
@@ -1867,9 +1869,9 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Generates a code flow based on a TSL function: Fn().
 	 *
-	 * @param {ShaderNodeInternal} node - TODO.
+	 * @param {ShaderNodeInternal} node - A function code will be generated based on the input.
 	 * @return {Object}
 	 */
 	flowShaderNode( shaderNode ) {
@@ -1911,10 +1913,10 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Runs the node flow through all the steps of creation, 'setup', 'analyze', 'generate'.
 	 *
-	 * @param {Node} node - TODO.
-	 * @param {String?} output - TODO.
+	 * @param {Node} node - The node to execute.
+	 * @param {String?} output - Expected output type. For example 'vec3'.
 	 * @return {Object}
 	 */
 	flowStagesNode( node, output = null ) {
@@ -1970,10 +1972,10 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Generates a code flow based on a child Node.
 	 *
-	 * @param {Node} node - TODO.
-	 * @param {String?} output - TODO.
+	 * @param {Node} node - The node to execute.
+	 * @param {String?} output - Expected output type. For example 'vec3'.
 	 * @return {Object}
 	 */
 	flowChildNode( node, output = null ) {
@@ -1995,12 +1997,15 @@ class NodeBuilder {
 	}
 
 	/**
-	 * TODO
+	 * Executes a flow of code in a different stage.
+	 *
+	 * Some nodes like `varying()` have the ability to compute code in vertex-stage and
+	 * return the value in fragment-stage even if it is being executed in an input fragment.
 	 *
 	 * @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
-	 * @param {Node} node - TODO.
-	 * @param {String?} output - TODO.
-	 * @param {String?} propertyName - TODO.
+	 * @param {Node} node - The node to execute.
+	 * @param {String?} output - Expected output type. For example 'vec3'.
+	 * @param {String?} propertyName - The property name to assign the result.
 	 * @return {Object}
 	 */
 	flowNodeFromShaderStage( shaderStage, node, output = null, propertyName = null ) {

src/nodes/core/StackNode.js

@@ -3,7 +3,8 @@ import { select } from '../math/ConditionalNode.js';
 import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../tsl/TSLBase.js';
 
 /**
- * TODO
+ * Stack is a helper for Nodes that need to produce stack-based code instead of continuous flow.
+ * They are usually needed in cases like `If`, `Else`.
  *
  * @augments Node
  */