Node: Document more modules. (mrdoob#30109)

* Node: Document more modules.

* Node: Document more modules.

* Docs: Clean up.

src/nodes/accessors/BufferNode.js

@@ -1,6 +1,22 @@
 import UniformNode from '../core/UniformNode.js';
 import { nodeObject } from '../tsl/TSLBase.js';
 
+/** @module BufferNode **/
+
+/**
+ * A special type of uniform node which represents array-like data
+ * as uniform buffers. The access usually happens via `element()`
+ * which returns an instance of {@link ArrayElementNode}. For example:
+ *
+ * ```js
+ * const bufferNode = buffer( array, 'mat4', count );
+ * const matrixNode = bufferNode.element( index ); // access a matrix from the buffer
+ * ```
+ * In general, it is recommened to use the more managed {@link UniformArrayNode}
+ * since it handles more input types and automatically cares about buffer paddings.
+ *
+ * @augments module:UniformNode~UniformNode
+ */
 class BufferNode extends UniformNode {
 
 	static get type() {
@@ -9,23 +25,61 @@ class BufferNode extends UniformNode {
 
 	}
 
+	/**
+	 * Constructs a new buffer node.
+	 *
+	 * @param {Array<Number>} value - Array-like buffer data.
+	 * @param {String} bufferType - The data type of the buffer.
+	 * @param {Number} [bufferCount=0] - The count of buffer elements.
+	 */
 	constructor( value, bufferType, bufferCount = 0 ) {
 
 		super( value, bufferType );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isBufferNode = true;
 
+		/**
+		 * The data type of the buffer.
+		 *
+		 * @type {String}
+		 */
 		this.bufferType = bufferType;
+
+		/**
+		 * The uniform node that holds the value of the reference node.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.bufferCount = bufferCount;
 
 	}
 
+	/**
+	 * The data type of the buffer elements.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The element type.
+	 */
 	getElementType( builder ) {
 
 		return this.getNodeType( builder );
 
 	}
 
+	/**
+	 * Overwrites the default implementation to return a fixed value `'buffer'`.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The input type.
+	 */
 	getInputType( /*builder*/ ) {
 
 		return 'buffer';
@@ -36,4 +90,13 @@ class BufferNode extends UniformNode {
 
 export default BufferNode;
 
+/**
+ * TSL function for creating a buffer node.
+ *
+ * @function
+ * @param {Array} value - Array-like buffer data.
+ * @param {String} type - The data type of a buffer element.
+ * @param {Number} count - The count of buffer elements.
+ * @returns {BufferNode}
+ */
 export const buffer = ( value, type, count ) => nodeObject( new BufferNode( value, type, count ) );

src/nodes/accessors/Normal.js

@@ -5,8 +5,20 @@ import { mat3, vec3, Fn, varying } from '../tsl/TSLBase.js';
 import { positionView } from './Position.js';
 import { faceDirection } from '../display/FrontFacingNode.js';
 
+/** @module Normal **/
+
+/**
+ * TSL object that represents the normal attribute of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const normalGeometry = /*@__PURE__*/ attribute( 'normal', 'vec3' );
 
+/**
+ * TSL object that represents the vertex normal in local space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const normalLocal = /*@__PURE__*/ ( Fn( ( builder ) => {
 
 	if ( builder.geometry.hasAttribute( 'normal' ) === false ) {
@@ -21,8 +33,18 @@ export const normalLocal = /*@__PURE__*/ ( Fn( ( builder ) => {
 
 }, 'vec3' ).once() )().toVar( 'normalLocal' );
 
+/**
+ * TSL object that represents the flat vertex normal in view space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const normalFlat = /*@__PURE__*/ positionView.dFdx().cross( positionView.dFdy() ).normalize().toVar( 'normalFlat' );
 
+/**
+ * TSL object that represents the vertex normal in view space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const normalView = /*@__PURE__*/ ( Fn( ( builder ) => {
 
 	let node;
@@ -41,23 +63,50 @@ export const normalView = /*@__PURE__*/ ( Fn( ( builder ) => {
 
 }, 'vec3' ).once() )().toVar( 'normalView' );
 
+/**
+ * TSL object that represents the vertex normal in world space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const normalWorld = /*@__PURE__*/ varying( normalView.transformDirection( cameraViewMatrix ), 'v_normalWorld' ).normalize().toVar( 'normalWorld' );
 
+/**
+ * TSL object that represents the transformed vertex normal in view space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const transformedNormalView = /*@__PURE__*/ ( Fn( ( builder ) => {
 
 	return builder.context.setupNormal();
 
 }, 'vec3' ).once() )().mul( faceDirection ).toVar( 'transformedNormalView' );
 
-
+/**
+ * TSL object that represents the transformed vertex normal in world space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const transformedNormalWorld = /*@__PURE__*/ transformedNormalView.transformDirection( cameraViewMatrix ).toVar( 'transformedNormalWorld' );
 
+/**
+ * TSL object that represents the transformed clearcoat vertex normal in view space of the current rendered object.
+ *
+ * @type {Node<vec3>}
+ */
 export const transformedClearcoatNormalView = /*@__PURE__*/ ( Fn( ( builder ) => {
 
 	return builder.context.setupClearcoatNormal();
 
 }, 'vec3' ).once() )().mul( faceDirection ).toVar( 'transformedClearcoatNormalView' );
 
+/**
+ * Transforms the normal with the given matrix.
+ *
+ * @function
+ * @param {Node<vec3>} normal - The normal.
+ * @param {Node<mat3>} [matrix=modelWorldMatrix] - The matrix.
+ * @return {Node<vec3>} The transformed normal.
+ */
 export const transformNormal = /*@__PURE__*/ Fn( ( [ normal, matrix = modelWorldMatrix ] ) => {
 
 	const m = mat3( matrix );
@@ -68,6 +117,14 @@ export const transformNormal = /*@__PURE__*/ Fn( ( [ normal, matrix = modelWorld
 
 } );
 
+/**
+ * Transforms the given normal from local to view space.
+ *
+ * @function
+ * @param {Node<vec3>} normal - The normal.
+ * @param {NodeBuilder} builder - The current node builder.
+ * @return {Node<vec3>} The transformed normal.
+ */
 export const transformNormalToView = /*@__PURE__*/ Fn( ( [ normal ], builder ) => {
 
 	const modelNormalViewMatrix = builder.renderer.nodes.modelNormalViewMatrix;

src/nodes/accessors/Position.js

@@ -19,7 +19,7 @@ export const positionLocal = /*@__PURE__*/ positionGeometry.varying( 'positionLo
 
 /**
  * TSL object that represents the previous vertex position in local space of the current rendered object.
- * Used in context of {@link VelocityNode} for rendering motion vectors.
+ * Used in context of {@link module:VelocityNode~VelocityNode} for rendering motion vectors.
  *
  * @type {AttributeNode<vec3>}
  */

src/nodes/accessors/ReferenceNode.js

@@ -36,7 +36,7 @@ class ReferenceElementNode extends ArrayElementNode {
 		super( referenceNode, indexNode );
 
 		/**
-		 * Similar to {@link ReferenceNode#reference}, an additional
+		 * Similar to {@link module:ReferenceNode~ReferenceNode#reference}, an additional
 		 * property references to the current node.
 		 *
 		 * @type {Node}
@@ -83,7 +83,7 @@ class ReferenceElementNode extends ArrayElementNode {
 /**
  * This type of node establishes a reference to a property of another object.
  * In this way, the value of the node is automatically linked to the value of
- * referenced object. Reference nodes internally represents the linked value
+ * referenced object. Reference nodes internally represent the linked value
  * as a uniform.
  *
  * @augments Node
@@ -147,7 +147,7 @@ class ReferenceNode extends Node {
 		this.properties = property.split( '.' );
 
 		/**
-		 * Points to the current referred object. This property exists next to {@link ReferenceNode#object}
+		 * Points to the current referred object. This property exists next to {@link module:ReferenceNode~ReferenceNode#object}
 		 * since the final reference might be updated from calling code.
 		 *
 		 * @type {Object?}
@@ -318,7 +318,7 @@ class ReferenceNode extends Node {
 
 	/**
 	 * Allows to update the reference based on the given state. The state is only
-	 * evaluated {@link ReferenceNode#object} is not set.
+	 * evaluated {@link module:ReferenceNode~ReferenceNode#object} is not set.
 	 *
 	 * @param {(NodeFrame|NodeBuilder)} state - The current state.
 	 * @return {Object} The updated reference.
@@ -383,7 +383,7 @@ class ReferenceNode extends Node {
 export default ReferenceNode;
 
 /**
- * TSL function for creating a reference node with the given parameters.
+ * TSL function for creating a reference node.
  *
  * @function
  * @param {String} name - The name of the property the node refers to.
@@ -394,7 +394,7 @@ export default ReferenceNode;
 export const reference = ( name, type, object ) => nodeObject( new ReferenceNode( name, type, object ) );
 
 /**
- * TSL function for creating a reference node with the given parameters.
+ * TSL function for creating a reference node.
  *
  * @function
  * @param {String} name - The name of the property the node refers to.

src/nodes/accessors/Tangent.js

@@ -3,6 +3,13 @@ import { cameraViewMatrix } from './Camera.js';
 import { modelViewMatrix } from './ModelNode.js';
 import { Fn, vec4 } from '../tsl/TSLBase.js';
 
+/** @module Tangent **/
+
+/**
+ * TSL object that represents the tangent attribute of the current rendered object.
+ *
+ * @type {Node<vec4>}
+ */
 export const tangentGeometry = /*@__PURE__*/ Fn( ( builder ) => {
 
 	if ( builder.geometry.hasAttribute( 'tangent' ) === false ) {
@@ -15,8 +22,37 @@ export const tangentGeometry = /*@__PURE__*/ Fn( ( builder ) => {
 
 } )();
 
+/**
+ * TSL object that represents the vertex tangent in local space of the current rendered object.
+ *
+ * @type {Node<vec4>}
+ */
 export const tangentLocal = /*@__PURE__*/ tangentGeometry.xyz.toVar( 'tangentLocal' );
+
+/**
+ * TSL object that represents the vertex tangent in view space of the current rendered object.
+ *
+ * @type {Node<vec4>}
+ */
 export const tangentView = /*@__PURE__*/ modelViewMatrix.mul( vec4( tangentLocal, 0 ) ).xyz.varying( 'v_tangentView' ).normalize().toVar( 'tangentView' );
+
+/**
+ * TSL object that represents the vertex tangent in world space of the current rendered object.
+ *
+ * @type {Node<vec4>}
+ */
 export const tangentWorld = /*@__PURE__*/ tangentView.transformDirection( cameraViewMatrix ).varying( 'v_tangentWorld' ).normalize().toVar( 'tangentWorld' );
+
+/**
+ * TSL object that represents the transformed vertex tangent in view space of the current rendered object.
+ *
+ * @type {Node<vec4>}
+ */
 export const transformedTangentView = /*@__PURE__*/ tangentView.toVar( 'transformedTangentView' );
+
+/**
+ * TSL object that represents the transformed vertex tangent in world space of the current rendered object.
+ *
+ * @type {Node<vec4>}
+ */
 export const transformedTangentWorld = /*@__PURE__*/ transformedTangentView.transformDirection( cameraViewMatrix ).normalize().toVar( 'transformedTangentWorld' );

src/nodes/accessors/TextureSizeNode.js

@@ -68,7 +68,7 @@ class TextureSizeNode extends Node {
 export default TextureSizeNode;
 
 /**
- * TSL function for creating a texture size node with the given parameters.
+ * TSL function for creating a texture size node.
  *
  * @function
  * @param {TextureNode} textureNode - A texture node which size should be retrieved.