From 9cbc4026ee1373633ad920712c300e39ae154fbd Mon Sep 17 00:00:00 2001
From: David Briscoe <43559+idbrii@users.noreply.github.com>
Date: Sun, 23 Jul 2023 02:43:22 -0700
Subject: [PATCH] doc: Clarify when to construct a StringName ahead of time

Fix docs don't give justification for manual construction.

Clarify how to apply manual StringName construction as an
optimization and that "string intern" means "work at parse time".

There are several godot-demo-projects (including 3d/platformer) that
incorrectly use StringName literals (they use & literals instead of just
passing strings), so clearly this is confusing.

AThousandShips did a disassembly test to prove it automatically converts
constant strings to StringName for annotated functions:

  func do_test(_var: StringName, _var2: String):
  pass

  func test():
  do_test("abc", "def")

Yields:

  Disassembling do_test(_var, _var2)
   0: line 2:     pass
   2: == END ==

  Disassembling test()
   0: line 5:     do_test("abc", "def")
   2: call self.do_test(const(&"abc"), const("def"))
   10: assign stack(3) = false
   12: == END ==

It also happens with built-in functions such as those of Input.
---
 doc/classes/StringName.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml
index 0814a30a8de..c0ed6b10468 100644
--- a/doc/classes/StringName.xml
+++ b/doc/classes/StringName.xml
@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		[StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). Two [StringName]s with the same value are the same object. Comparing them is extremely fast compared to regular [String]s.
-		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 the [StringName] constructor or, in GDScript, the literal syntax [code]&amp;"example"[/code].
+		You will usually pass a [String] to methods expecting a [StringName] and it will be automatically converted (often at compile time), but in rare cases you can construct a [StringName] ahead of time with the [StringName] constructor or, in GDScript, the literal syntax [code]&amp;"example"[/code]. Manually constructing a [StringName] allows you to control when the conversion from [String] occurs or to use the literal and prevent conversions entirely.
 		See also [NodePath], which is a similar concept specifically designed to store pre-parsed scene tree paths.
 		All of [String]'s methods are available in this class too. They convert the [StringName] into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired.
 		[b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code]. The [code]not[/code] operator cannot be used. Instead, [method is_empty] should be used to check for empty [StringName]s.