Nixyri/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2025-01-21 01:11:20 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Improve documentation for NodePath and StringName

Browse Source 
- Update the NodePath shorthand prefix for `master`.
- Document the StringName construction shorthand (`&"example"`).
- Cross-link between NodePath and StringName, as these are related
  concepts.
This commit is contained in:
Hugo Locurcio 2022-03-13 01:04:51 +01:00
parent 6721290831
commit 51896c4682
No known key found for this signature in database
GPG Key ID: 39E8F8BE30B0A49C
2 changed files with 15 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/classes/NodePath.xml
View File

@ -5,21 +5,22 @@
</brief_description>
<description>
A pre-parsed relative or absolute path in a scene tree, for use with [method Node.get_node] and similar functions. It can reference a node, a resource within a node, or a property of a node or resource. For instance, [code]"Path2D/PathFollow2D/Sprite2D:texture:size"[/code] would refer to the [code]size[/code] property of the [code]texture[/code] resource on the node named [code]"Sprite2D"[/code] which is a child of the other named nodes in the path.
You will usually just pass a string to [method Node.get_node] and it will be automatically converted, but you may occasionally want to parse a path ahead of time with [NodePath] or the literal syntax [code]@"path"[/code]. Exporting a [NodePath] variable will give you a node selection widget in the properties panel of the editor, which can often be useful.
You will usually just pass a string to [method Node.get_node] and it will be automatically converted, but you may occasionally want to parse a path ahead of time with [NodePath] or the literal syntax [code]^"path"[/code]. Exporting a [NodePath] variable will give you a node selection widget in the properties panel of the editor, which can often be useful.
A [NodePath] is composed of a list of slash-separated node names (like a filesystem path) and an optional colon-separated list of "subnames" which can be resources or properties.
Some examples of NodePaths include the following:
[codeblock]
# No leading slash means it is relative to the current node.
@"A" # Immediate child A
@"A/B" # A's child B
@"." # The current node.
@".." # The parent node.
@"../C" # A sibling node C.
^"A" # Immediate child A
^"A/B" # A's child B
^"." # The current node.
^".." # The parent node.
^"../C" # A sibling node C.
# A leading slash means it is absolute from the SceneTree.
@"/root" # Equivalent to get_tree().get_root().
@"/root/Main" # If your main scene's root node were named "Main".
@"/root/MyAutoload" # If you have an autoloaded node or scene.
^"/root" # Equivalent to get_tree().get_root().
^"/root/Main" # If your main scene's root node were named "Main".
^"/root/MyAutoload" # If you have an autoloaded node or scene.
[/codeblock]
See also [StringName], which is a similar concept for general-purpose string interning.
[b]Note:[/b] In the editor, [NodePath] properties are automatically updated when moving, renaming or deleting a node in the scene tree, but they are never updated at runtime.
</description>
<tutorials>
@ -36,7 +37,7 @@
<return type="NodePath" />
<argument index="0" name="from" type="NodePath" />
<description>
Constructs a [NodePath] as a copy of the given [NodePath].
Constructs a [NodePath] as a copy of the given [NodePath]. [code]NodePath("example")[/code] is equivalent to [code]^"example"[/code].
</description>
</constructor>
<constructor name="NodePath">

6
doc/classes/StringName.xml
View File

@ -4,7 +4,9 @@
An optimized string type for unique names.
</brief_description>
<description>
[StringName]s are immutable strings designed for general-purpose representation of unique names. [StringName] ensures that only one instance of a given name exists (so two [StringName]s with the same value are the same object). Comparing them is much faster than with regular [String]s, because only the pointers are compared, not the whole strings.
[StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). [StringName] ensures that only one instance of a given name exists (so two [StringName]s with the same value are the same object). Comparing them is much faster than with regular [String]s, because only the pointers are compared, not the whole strings.
You will usually just pass a [String] to methods expecting a [StringName] and it will be automatically converted, but you may occasionally want to construct a [StringName] ahead of time with [StringName] or the literal syntax [code]&amp;"example"[/code].
See also [NodePath], which is a similar concept specifically designed to store pre-parsed node paths.
</description>
<tutorials>
</tutorials>
@ -26,7 +28,7 @@
<return type="StringName" />
<argument index="0" name="from" type="String" />
<description>
Creates a new [StringName] from the given [String].
Creates a new [StringName] from the given [String]. [code]StringName("example")[/code] is equivalent to [code]&amp;"example"[/code].
</description>
</constructor>
</constructors>