Document GLTFNode and some of GLTFState

(cherry picked from commit 2cc22fb964a94cdb031dd95f473812eef274c903)

2 files changed, 39 insertions, 0 deletions

diff --git a/modules/gltf/doc_classes/GLTFNode.xml b/modules/gltf/doc_classes/GLTFNode.xml
index f3b3e61501..b9223bfdfa 100644
--- a/modules/gltf/doc_classes/GLTFNode.xml
+++ b/modules/gltf/doc_classes/GLTFNode.xml
@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		Represents a GLTF node. GLTF nodes may have names, transforms, children (other GLTF nodes), and more specialized properties (represented by their own classes).
+		GLTF nodes generally exist inside of [GLTFState] which represents all data of a GLTF file. Most of GLTFNode's properties are indices of other data in the GLTF file. You can extend a GLTF node with additional properties by using [method get_additional_data] and [method set_additional_data].
 	</description>
 	<tutorials>
 		<link title="GLTF scene and node spec">https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_004_ScenesNodes.md"</link>
@@ -30,28 +31,40 @@
 	</methods>
 	<members>
 		<member name="camera" type="int" setter="set_camera" getter="get_camera" default="-1">
+			If this GLTF node is a camera, the index of the [GLTFCamera] in the [GLTFState] that describes the camera's properties. If -1, this node is not a camera.
 		</member>
 		<member name="children" type="PackedInt32Array" setter="set_children" getter="get_children" default="PackedInt32Array()">
+			The indices of the children nodes in the [GLTFState]. If this GLTF node has no children, this will be an empty array.
 		</member>
 		<member name="height" type="int" setter="set_height" getter="get_height" default="-1">
+			How deep into the node hierarchy this node is. A root node will have a height of 0, its children will have a height of 1, and so on. If -1, the height has not been calculated.
 		</member>
 		<member name="light" type="int" setter="set_light" getter="get_light" default="-1">
+			If this GLTF node is a light, the index of the [GLTFLight] in the [GLTFState] that describes the light's properties. If -1, this node is not a light.
 		</member>
 		<member name="mesh" type="int" setter="set_mesh" getter="get_mesh" default="-1">
+			If this GLTF node is a mesh, the index of the [GLTFMesh] in the [GLTFState] that describes the mesh's properties. If -1, this node is not a mesh.
 		</member>
 		<member name="parent" type="int" setter="set_parent" getter="get_parent" default="-1">
+			The index of the parent node in the [GLTFState]. If -1, this node is a root node.
 		</member>
 		<member name="position" type="Vector3" setter="set_position" getter="get_position" default="Vector3(0, 0, 0)">
+			The position of the GLTF node relative to its parent.
 		</member>
 		<member name="rotation" type="Quaternion" setter="set_rotation" getter="get_rotation" default="Quaternion(0, 0, 0, 1)">
+			The rotation of the GLTF node relative to its parent.
 		</member>
 		<member name="scale" type="Vector3" setter="set_scale" getter="get_scale" default="Vector3(1, 1, 1)">
+			The scale of the GLTF node relative to its parent.
 		</member>
 		<member name="skeleton" type="int" setter="set_skeleton" getter="get_skeleton" default="-1">
+			If this GLTF node has a skeleton, the index of the [GLTFSkeleton] in the [GLTFState] that describes the skeleton's properties. If -1, this node does not have a skeleton.
 		</member>
 		<member name="skin" type="int" setter="set_skin" getter="get_skin" default="-1">
+			If this GLTF node has a skin, the index of the [GLTFSkin] in the [GLTFState] that describes the skin's properties. If -1, this node does not have a skin.
 		</member>
 		<member name="xform" type="Transform3D" setter="set_xform" getter="get_xform" default="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)">
+			The transform of the GLTF node relative to its parent. This property is usually unused since the position, rotation, and scale properties are preferred.
 		</member>
 	</members>
 </class>
diff --git a/modules/gltf/doc_classes/GLTFState.xml b/modules/gltf/doc_classes/GLTFState.xml
index 33b92f37c8..7a46fb8dfc 100644
--- a/modules/gltf/doc_classes/GLTFState.xml
+++ b/modules/gltf/doc_classes/GLTFState.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GLTFState" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
+		Represents all data of a GLTF file.
 	</brief_description>
 	<description>
+		Contains all nodes and resources of a GLTF file. This is used by [GLTFDocument] as data storage, which allows [GLTFDocument] and all [GLTFDocumentExtension] classes to remain stateless.
+		GLTFState can be populated by [GLTFDocument] reading a file or by converting a Godot scene. Then the data can either be used to create a Godot scene or save to a GLTF file. The code that converts to/from a Godot scene can be intercepted at arbitrary points by [GLTFDocumentExtension] classes. This allows for custom data to be stored in the GLTF file or for custom data to be converted to/from Godot nodes.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -32,17 +35,20 @@
 			<return type="AnimationPlayer" />
 			<param index="0" name="idx" type="int" />
 			<description>
+				Returns the [AnimationPlayer] node with the given index. These nodes are only used during the export process when converting Godot [AnimationPlayer] nodes to GLTF animations.
 			</description>
 		</method>
 		<method name="get_animation_players_count">
 			<return type="int" />
 			<param index="0" name="idx" type="int" />
 			<description>
+				Returns the number of [AnimationPlayer] nodes in this [GLTFState]. These nodes are only used during the export process when converting Godot [AnimationPlayer] nodes to GLTF animations.
 			</description>
 		</method>
 		<method name="get_animations">
 			<return type="GLTFAnimation[]" />
 			<description>
+				Returns an array of all [GLTFAnimation]s in the GLTF file. When importing, these will be generated as animations in an [AnimationPlayer] node. When exporting, these will be generated from Godot [AnimationPlayer] nodes.
 			</description>
 		</method>
 		<method name="get_buffer_views">
@@ -53,6 +59,7 @@
 		<method name="get_cameras">
 			<return type="GLTFCamera[]" />
 			<description>
+				Returns an array of all [GLTFCamera]s in the GLTF file. These are the cameras that the [member GLTFNode.camera] index refers to.
 			</description>
 		</method>
 		<method name="get_handle_binary_image">
@@ -68,6 +75,7 @@
 		<method name="get_lights">
 			<return type="GLTFLight[]" />
 			<description>
+				Returns an array of all [GLTFLight]s in the GLTF file. These are the lights that the [member GLTFNode.light] index refers to.
 			</description>
 		</method>
 		<method name="get_materials">
@@ -78,27 +86,32 @@
 		<method name="get_meshes">
 			<return type="GLTFMesh[]" />
 			<description>
+				Returns an array of all [GLTFMesh]es in the GLTF file. These are the meshes that the [member GLTFNode.mesh] index refers to.
 			</description>
 		</method>
 		<method name="get_nodes">
 			<return type="GLTFNode[]" />
 			<description>
+				Returns an array of all [GLTFNode]s in the GLTF file. These are the nodes that [member GLTFNode.children] and [member root_nodes] refer to. This includes nodes that may not be generated in the Godot scene, or nodes that may generate multiple Godot scene nodes.
 			</description>
 		</method>
 		<method name="get_scene_node">
 			<return type="Node" />
 			<param index="0" name="idx" type="int" />
 			<description>
+				Returns the Godot scene node that corresponds to the same index as the [GLTFNode] it was generated from. Not every [GLTFNode] will have a scene node generated, and not every generated scene node will have a corresponding [GLTFNode].
 			</description>
 		</method>
 		<method name="get_skeletons">
 			<return type="GLTFSkeleton[]" />
 			<description>
+				Returns an array of all [GLTFSkeleton]s in the GLTF file. These are the skeletons that the [member GLTFNode.skeleton] index refers to.
 			</description>
 		</method>
 		<method name="get_skins">
 			<return type="GLTFSkin[]" />
 			<description>
+				Returns an array of all [GLTFSkin]s in the GLTF file. These are the skins that the [member GLTFNode.skin] index refers to.
 			</description>
 		</method>
 		<method name="get_texture_samplers">
@@ -115,11 +128,13 @@
 		<method name="get_unique_animation_names">
 			<return type="String[]" />
 			<description>
+				Returns an array of unique animation names. This is only used during the import process.
 			</description>
 		</method>
 		<method name="get_unique_names">
 			<return type="String[]" />
 			<description>
+				Returns an array of unique node names. This is used in both the import process and export process.
 			</description>
 		</method>
 		<method name="set_accessors">
@@ -141,6 +156,7 @@
 			<return type="void" />
 			<param index="0" name="animations" type="GLTFAnimation[]" />
 			<description>
+				Sets the [GLTFAnimation]s in the state. When importing, these will be generated as animations in an [AnimationPlayer] node. When exporting, these will be generated from Godot [AnimationPlayer] nodes.
 			</description>
 		</method>
 		<method name="set_buffer_views">
@@ -153,6 +169,7 @@
 			<return type="void" />
 			<param index="0" name="cameras" type="GLTFCamera[]" />
 			<description>
+				Sets the [GLTFCamera]s in the state. These are the cameras that the [member GLTFNode.camera] index refers to.
 			</description>
 		</method>
 		<method name="set_handle_binary_image">
@@ -171,6 +188,7 @@
 			<return type="void" />
 			<param index="0" name="lights" type="GLTFLight[]" />
 			<description>
+				Sets the [GLTFLight]s in the state. These are the lights that the [member GLTFNode.light] index refers to.
 			</description>
 		</method>
 		<method name="set_materials">
@@ -183,24 +201,28 @@
 			<return type="void" />
 			<param index="0" name="meshes" type="GLTFMesh[]" />
 			<description>
+				Sets the [GLTFMesh]es in the state. These are the meshes that the [member GLTFNode.mesh] index refers to.
 			</description>
 		</method>
 		<method name="set_nodes">
 			<return type="void" />
 			<param index="0" name="nodes" type="GLTFNode[]" />
 			<description>
+				Sets the [GLTFNode]s in the state. These are the nodes that [member GLTFNode.children] and [member root_nodes] refer to. Some of the nodes set here may not be generated in the Godot scene, or may generate multiple Godot scene nodes.
 			</description>
 		</method>
 		<method name="set_skeletons">
 			<return type="void" />
 			<param index="0" name="skeletons" type="GLTFSkeleton[]" />
 			<description>
+				Sets the [GLTFSkeleton]s in the state. These are the skeletons that the [member GLTFNode.skeleton] index refers to.
 			</description>
 		</method>
 		<method name="set_skins">
 			<return type="void" />
 			<param index="0" name="skins" type="GLTFSkin[]" />
 			<description>
+				Sets the [GLTFSkin]s in the state. These are the skins that the [member GLTFNode.skin] index refers to.
 			</description>
 		</method>
 		<method name="set_texture_samplers">
@@ -220,12 +242,14 @@
 			<return type="void" />
 			<param index="0" name="unique_animation_names" type="String[]" />
 			<description>
+				Sets the unique animation names in the state. This is only used during the import process.
 			</description>
 		</method>
 		<method name="set_unique_names">
 			<return type="void" />
 			<param index="0" name="unique_names" type="String[]" />
 			<description>
+				Sets the unique node names in the state. This is used in both the import process and export process.
 			</description>
 		</method>
 	</methods>
@@ -245,8 +269,10 @@
 		<member name="minor_version" type="int" setter="set_minor_version" getter="get_minor_version" default="0">
 		</member>
 		<member name="root_nodes" type="PackedInt32Array" setter="set_root_nodes" getter="get_root_nodes" default="PackedInt32Array()">
+			The root nodes of the GLTF file. Typically, a GLTF file will only have one scene, and therefore one root node. However, a GLTF file may have multiple scenes and therefore multiple root nodes, which will be generated as siblings of each other and as children of the root node of the generated Godot scene.
 		</member>
 		<member name="scene_name" type="String" setter="set_scene_name" getter="get_scene_name" default="&quot;&quot;">
+			The name of the scene. When importing, if not specified, this will be the file name. When exporting, if specified, the scene name will be saved to the GLTF file.
 		</member>
 		<member name="use_named_skin_binds" type="bool" setter="set_use_named_skin_binds" getter="get_use_named_skin_binds" default="false">
 		</member>