Clarify Intended Usage of getDataFromNode() and getNodeProperties()

[cmhhelgeson]

Description

For someone working with the node system for the first time, it can be diffucult to understand the difference between the getDataFromNode and getNodeProperties functions. Of course, reading how each function is used in each respective Node class clarifies the difference.

For instance, these are the keys that get assigned to the cached nodeData object for a node

nodeData.propertyName
nodeData.snippet
nodeData.initialized
nodeData.generated
nodeData.stages
nodeData.buildStages
nodeData.parentNodeBlock

These values largely correlate with the status of the node within the build process, the stages in which the node is being used, and the blocks where the node is being initialized or used.

Meanwhile, the properties object of a node, which itself comes from that node's cached nodeData, generally holds a node's dependencies, or references to other nodes that the current node needs to fully set itself up. It also can hold values representing the context for how two nodes are interacting with each other.

// Is this an assign operation?
properties.assign
// Dependency nodes
properties.uvNode
properties.levelNode
properties.biasNode
properties.compareNode
properties.depthNode
properties.textureNode
properties.sourceNode
properties.targetNode
// Assign a node's children as its properties
properties['node' + index++]
properties.varying

Solution

The simplest solution would be modifying the function signature of getNodeProperties. The function signature shouldn't just declare that it is returning 'properties'. It should also clarify what a 'property' is, and it differs from other cached node data. Ideally, getDataFromNode would also have its function signature changed to indicate how the data it returns is functionally different from that of getNodeProperties.

Alternatives

We could also change the names of the functions themselves to better indicate their respective functionality, but I think simply adding better definitions that explain the differences between nodeData and nodeProperties will be sufficient.

Most users largely won't mess around with the internals of the node system, but I believe it's benefical to add better signposting for those who do.

Additional context

No response

[cmhhelgeson]

#32004 Goes some way towards fixing this issue by clarifying common usage patterns for the getNodeProperties() function. A better definition for getDataFromNode and properties would still be great.