Merge pull request #82681 from akien-mga/doc-Node3DGizmo

Add docs for Node3DGizmo to clarify its link to EditorNode3DGizmo

doc/classes/EditorNode3DGizmo.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="EditorNode3DGizmo" inherits="Node3DGizmo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Gizmo for editing Node3D objects.
+		Gizmo for editing [Node3D] objects.
 	</brief_description>
 	<description>
-		Gizmo that is used for providing custom visualization and editing (handles and subgizmos) for Node3D objects. Can be overridden to create custom gizmos, but for simple gizmos creating a [EditorNode3DGizmoPlugin] is usually recommended.
+		Gizmo that is used for providing custom visualization and editing (handles and subgizmos) for [Node3D] objects. Can be overridden to create custom gizmos, but for simple gizmos creating a [EditorNode3DGizmoPlugin] is usually recommended.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -87,15 +87,15 @@
 			<param index="0" name="id" type="int" />
 			<param index="1" name="transform" type="Transform3D" />
 			<description>
-				Override this method to update the node properties during subgizmo editing (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). The [param transform] is given in the Node3D's local coordinate system.
+				Override this method to update the node properties during subgizmo editing (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). The [param transform] is given in the [Node3D]'s local coordinate system.
 			</description>
 		</method>
 		<method name="_subgizmos_intersect_frustum" qualifiers="virtual const">
 			<return type="PackedInt32Array" />
 			<param index="0" name="camera" type="Camera3D" />
 			<param index="1" name="frustum" type="Plane[]" />
 			<description>
-				Override this method to allow selecting subgizmos using mouse drag box selection. Given a [param camera] and a [param frustum], this method should return which subgizmos are contained within the frustum. The [param frustum] argument consists of an [code]Array[/code] with all the [code]Plane[/code]s that make up the selection frustum. The returned value should contain a list of unique subgizmo identifiers, which can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos].
+				Override this method to allow selecting subgizmos using mouse drag box selection. Given a [param camera] and a [param frustum], this method should return which subgizmos are contained within the frustum. The [param frustum] argument consists of an array with all the [code]Plane[/code]s that make up the selection frustum. The returned value should contain a list of unique subgizmo identifiers, which can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos].
 			</description>
 		</method>
 		<method name="_subgizmos_intersect_ray" qualifiers="virtual const">
@@ -128,7 +128,7 @@
 			<param index="3" name="billboard" type="bool" default="false" />
 			<param index="4" name="secondary" type="bool" default="false" />
 			<description>
-				Adds a list of handles (points) which can be used to edit the properties of the gizmo's Node3D. The [param ids] argument can be used to specify a custom identifier for each handle, if an empty [code]Array[/code] is passed, the ids will be assigned automatically from the [param handles] argument order.
+				Adds a list of handles (points) which can be used to edit the properties of the gizmo's [Node3D]. The [param ids] argument can be used to specify a custom identifier for each handle, if an empty array is passed, the ids will be assigned automatically from the [param handles] argument order.
 				The [param secondary] argument marks the added handles as secondary, meaning they will normally have lower selection priority than regular handles. When the user is holding the shift key secondary handles will switch to have higher priority than regular handles. This change in priority can be used to place multiple handles at the same point while still giving the user control on their selection.
 				There are virtual methods which will be called upon editing of these handles. Call this method during [method _redraw].
 			</description>

doc/classes/Node3D.xml

@@ -4,7 +4,7 @@
 		Most basic 3D game object, parent of all 3D-related nodes.
 	</brief_description>
 	<description>
-		Most basic 3D game object, with a [Transform3D] and visibility settings. All other 3D game objects inherit from Node3D. Use [Node3D] as a parent node to move, scale, rotate and show/hide children in a 3D project.
+		Most basic 3D game object, with a [Transform3D] and visibility settings. All other 3D game objects inherit from [Node3D]. Use [Node3D] as a parent node to move, scale, rotate and show/hide children in a 3D project.
 		Affine operations (rotate, scale, translate) happen in parent's local coordinate system, unless the [Node3D] object is set as top-level. Affine operations in this coordinate system correspond to direct affine operations on the [Node3D]'s transform. The word local below refers to this coordinate system. The coordinate system that is attached to the [Node3D] object itself is referred to as object-local coordinate system.
 		[b]Note:[/b] Unless otherwise specified, all methods that have angle parameters must have angles specified as [i]radians[/i]. To convert degrees to radians, use [method @GlobalScope.deg_to_rad].
 		[b]Note:[/b] Be aware that "Spatial" nodes are now called "Node3D" starting with Godot 4. Any Godot 3.x references to "Spatial" nodes refer to "Node3D" in Godot 4.
@@ -18,13 +18,14 @@
 			<return type="void" />
 			<param index="0" name="gizmo" type="Node3DGizmo" />
 			<description>
-				Attach a gizmo to this [code]Node3D[/code].
+				Attach an editor gizmo to this [Node3D].
+				[b]Note:[/b] The gizmo object would typically be an instance of [EditorNode3DGizmo], but the argument type is kept generic to avoid creating a dependency on editor classes in [Node3D].
 			</description>
 		</method>
 		<method name="clear_gizmos">
 			<return type="void" />
 			<description>
-				Clear all gizmos attached to this [code]Node3D[/code].
+				Clear all gizmos attached to this [Node3D].
 			</description>
 		</method>
 		<method name="clear_subgizmo_selection">
@@ -42,7 +43,7 @@
 		<method name="get_gizmos" qualifiers="const">
 			<return type="Node3DGizmo[]" />
 			<description>
-				Returns all the gizmos attached to this [code]Node3D[/code].
+				Returns all the gizmos attached to this [Node3D].
 			</description>
 		</method>
 		<method name="get_parent_node_3d" qualifiers="const">
@@ -223,6 +224,7 @@
 			<param index="2" name="transform" type="Transform3D" />
 			<description>
 				Set subgizmo selection for this node in the editor.
+				[b]Note:[/b] The gizmo object would typically be an instance of [EditorNode3DGizmo], but the argument type is kept generic to avoid creating a dependency on editor classes in [Node3D].
 			</description>
 		</method>
 		<method name="show">
@@ -263,7 +265,7 @@
 		<method name="update_gizmos">
 			<return type="void" />
 			<description>
-				Updates all the [Node3DGizmo]s attached to this node.
+				Updates all the [Node3D] gizmos attached to this node.
 			</description>
 		</method>
 	</methods>
@@ -334,20 +336,20 @@
 	</signals>
 	<constants>
 		<constant name="NOTIFICATION_TRANSFORM_CHANGED" value="2000">
-			Node3D nodes receives this notification when their global transform changes. This means that either the current or a parent node changed its transform.
+			[Node3D] nodes receive this notification when their global transform changes. This means that either the current or a parent node changed its transform.
 			In order for [constant NOTIFICATION_TRANSFORM_CHANGED] to work, users first need to ask for it, with [method set_notify_transform]. The notification is also sent if the node is in the editor context and it has at least one valid gizmo.
 		</constant>
 		<constant name="NOTIFICATION_ENTER_WORLD" value="41">
-			Node3D nodes receives this notification when they are registered to new [World3D] resource.
+			[Node3D] nodes receive this notification when they are registered to new [World3D] resource.
 		</constant>
 		<constant name="NOTIFICATION_EXIT_WORLD" value="42">
-			Node3D nodes receives this notification when they are unregistered from current [World3D] resource.
+			[Node3D] nodes receive this notification when they are unregistered from current [World3D] resource.
 		</constant>
 		<constant name="NOTIFICATION_VISIBILITY_CHANGED" value="43">
-			Node3D nodes receives this notification when their visibility changes.
+			[Node3D] nodes receive this notification when their visibility changes.
 		</constant>
 		<constant name="NOTIFICATION_LOCAL_TRANSFORM_CHANGED" value="44">
-			Node3D nodes receives this notification when their local transform changes. This is not received when the transform of a parent node is changed.
+			[Node3D] nodes receive this notification when their local transform changes. This is not received when the transform of a parent node is changed.
 			In order for [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] to work, users first need to ask for it, with [method set_notify_local_transform].
 		</constant>
 		<constant name="ROTATION_EDIT_MODE_EULER" value="0" enum="RotationEditMode">

doc/classes/Node3DGizmo.xml

@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="Node3DGizmo" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Abstract class to expose editor gizmos for [Node3D].
 	</brief_description>
 	<description>
+		This abstract class helps connect the [Node3D] scene with the editor-specific [EditorNode3DGizmo] class.
+		[Node3DGizmo] by itself has no exposed API, refer to [method Node3D.add_gizmo] and pass it an [EditorNode3DGizmo] instance.
 	</description>
 	<tutorials>
 	</tutorials>