Merge pull request #30202 from akien-mga/doc-globalscope

doc: Complete GlobalScope documentation

1 files changed, 117 insertions, 53 deletions

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index 4f5e1a27db..6c1f4f8c85 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -648,7 +648,7 @@
 			_ key.
 		</constant>
 		<constant name="KEY_QUOTELEFT" value="96" enum="KeyList">
-			Left Quote key.
+			` key.
 		</constant>
 		<constant name="KEY_BRACELEFT" value="123" enum="KeyList">
 			{ key.
@@ -675,9 +675,10 @@
 			£ key.
 		</constant>
 		<constant name="KEY_CURRENCY" value="164" enum="KeyList">
+			¤ key.
 		</constant>
 		<constant name="KEY_YEN" value="165" enum="KeyList">
-			Yen key.
+			¥ key.
 		</constant>
 		<constant name="KEY_BROKENBAR" value="166" enum="KeyList">
 			¦ key.
@@ -692,21 +693,22 @@
 			© key.
 		</constant>
 		<constant name="KEY_ORDFEMININE" value="170" enum="KeyList">
+			ª key.
 		</constant>
 		<constant name="KEY_GUILLEMOTLEFT" value="171" enum="KeyList">
 			« key.
 		</constant>
 		<constant name="KEY_NOTSIGN" value="172" enum="KeyList">
-			» key.
+			¬ key.
 		</constant>
 		<constant name="KEY_HYPHEN" value="173" enum="KeyList">
-			‐ key.
+			Soft hyphen key.
 		</constant>
 		<constant name="KEY_REGISTERED" value="174" enum="KeyList">
 			® key.
 		</constant>
 		<constant name="KEY_MACRON" value="175" enum="KeyList">
-			Macron key.
+			¯ key.
 		</constant>
 		<constant name="KEY_DEGREE" value="176" enum="KeyList">
 			° key.
@@ -727,19 +729,19 @@
 			µ key.
 		</constant>
 		<constant name="KEY_PARAGRAPH" value="182" enum="KeyList">
-			§ key.
+			¶ key.
 		</constant>
 		<constant name="KEY_PERIODCENTERED" value="183" enum="KeyList">
 			· key.
 		</constant>
 		<constant name="KEY_CEDILLA" value="184" enum="KeyList">
-			¬ key.
+			¸ key.
 		</constant>
 		<constant name="KEY_ONESUPERIOR" value="185" enum="KeyList">
 			¹ key.
 		</constant>
 		<constant name="KEY_MASCULINE" value="186" enum="KeyList">
-			♂ key.
+			º key.
 		</constant>
 		<constant name="KEY_GUILLEMOTRIGHT" value="187" enum="KeyList">
 			» key.
@@ -757,97 +759,97 @@
 			¿ key.
 		</constant>
 		<constant name="KEY_AGRAVE" value="192" enum="KeyList">
-			à key.
+			À key.
 		</constant>
 		<constant name="KEY_AACUTE" value="193" enum="KeyList">
-			á key.
+			Á key.
 		</constant>
 		<constant name="KEY_ACIRCUMFLEX" value="194" enum="KeyList">
-			â key.
+			Â key.
 		</constant>
 		<constant name="KEY_ATILDE" value="195" enum="KeyList">
-			ã key.
+			Ã key.
 		</constant>
 		<constant name="KEY_ADIAERESIS" value="196" enum="KeyList">
-			ä key.
+			Ä key.
 		</constant>
 		<constant name="KEY_ARING" value="197" enum="KeyList">
-			å key.
+			Å key.
 		</constant>
 		<constant name="KEY_AE" value="198" enum="KeyList">
-			æ key.
+			Æ key.
 		</constant>
 		<constant name="KEY_CCEDILLA" value="199" enum="KeyList">
-			ç key.
+			Ç key.
 		</constant>
 		<constant name="KEY_EGRAVE" value="200" enum="KeyList">
-			è key.
+			È key.
 		</constant>
 		<constant name="KEY_EACUTE" value="201" enum="KeyList">
-			é key.
+			É key.
 		</constant>
 		<constant name="KEY_ECIRCUMFLEX" value="202" enum="KeyList">
-			ê key.
+			Ê key.
 		</constant>
 		<constant name="KEY_EDIAERESIS" value="203" enum="KeyList">
-			ë key.
+			Ë key.
 		</constant>
 		<constant name="KEY_IGRAVE" value="204" enum="KeyList">
-			ì key.
+			Ì key.
 		</constant>
 		<constant name="KEY_IACUTE" value="205" enum="KeyList">
-			í key.
+			Í key.
 		</constant>
 		<constant name="KEY_ICIRCUMFLEX" value="206" enum="KeyList">
-			î key.
+			Î key.
 		</constant>
 		<constant name="KEY_IDIAERESIS" value="207" enum="KeyList">
-			ë key.
+			Ï key.
 		</constant>
 		<constant name="KEY_ETH" value="208" enum="KeyList">
-			ð key.
+			Ð key.
 		</constant>
 		<constant name="KEY_NTILDE" value="209" enum="KeyList">
-			ñ key.
+			Ñ key.
 		</constant>
 		<constant name="KEY_OGRAVE" value="210" enum="KeyList">
-			ò key.
+			Ò key.
 		</constant>
 		<constant name="KEY_OACUTE" value="211" enum="KeyList">
-			ó key.
+			Ó key.
 		</constant>
 		<constant name="KEY_OCIRCUMFLEX" value="212" enum="KeyList">
-			ô key.
+			Ô key.
 		</constant>
 		<constant name="KEY_OTILDE" value="213" enum="KeyList">
-			õ key.
+			Õ key.
 		</constant>
 		<constant name="KEY_ODIAERESIS" value="214" enum="KeyList">
-			ö key.
+			Ö key.
 		</constant>
 		<constant name="KEY_MULTIPLY" value="215" enum="KeyList">
 			× key.
 		</constant>
 		<constant name="KEY_OOBLIQUE" value="216" enum="KeyList">
-			ø key.
+			Ø key.
 		</constant>
 		<constant name="KEY_UGRAVE" value="217" enum="KeyList">
-			ù key.
+			Ù key.
 		</constant>
 		<constant name="KEY_UACUTE" value="218" enum="KeyList">
-			ú key.
+			Ú key.
 		</constant>
 		<constant name="KEY_UCIRCUMFLEX" value="219" enum="KeyList">
-			û key.
+			Û key.
 		</constant>
 		<constant name="KEY_UDIAERESIS" value="220" enum="KeyList">
-			ü key.
+			Ü key.
 		</constant>
 		<constant name="KEY_YACUTE" value="221" enum="KeyList">
-			ý key.
+			Ý key.
 		</constant>
 		<constant name="KEY_THORN" value="222" enum="KeyList">
-			þ key.
+			Þ key.
 		</constant>
 		<constant name="KEY_SSHARP" value="223" enum="KeyList">
 			ß key.
@@ -1084,8 +1086,10 @@
 			Gamepad right stick vertical axis.
 		</constant>
 		<constant name="JOY_AXIS_4" value="4" enum="JoystickList">
+			Generic gamepad axis 4.
 		</constant>
 		<constant name="JOY_AXIS_5" value="5" enum="JoystickList">
+			Generic gamepad axis 5.
 		</constant>
 		<constant name="JOY_AXIS_6" value="6" enum="JoystickList">
 			Gamepad left trigger analog axis.
@@ -1094,8 +1098,10 @@
 			Gamepad right trigger analog axis.
 		</constant>
 		<constant name="JOY_AXIS_8" value="8" enum="JoystickList">
+			Generic gamepad axis 8.
 		</constant>
 		<constant name="JOY_AXIS_9" value="9" enum="JoystickList">
+			Generic gamepad axis 9.
 		</constant>
 		<constant name="JOY_AXIS_MAX" value="10" enum="JoystickList">
 			Represents the maximum number of joystick axes supported.
@@ -1131,18 +1137,25 @@
 			OpenVR touchpad Y axis (Joystick axis on Oculus Touch and Windows MR controllers).
 		</constant>
 		<constant name="MIDI_MESSAGE_NOTE_OFF" value="8" enum="MidiMessageList">
+			MIDI note OFF message.
 		</constant>
 		<constant name="MIDI_MESSAGE_NOTE_ON" value="9" enum="MidiMessageList">
+			MIDI note ON message.
 		</constant>
 		<constant name="MIDI_MESSAGE_AFTERTOUCH" value="10" enum="MidiMessageList">
+			MIDI aftertouch message.
 		</constant>
 		<constant name="MIDI_MESSAGE_CONTROL_CHANGE" value="11" enum="MidiMessageList">
+			MIDI control change message.
 		</constant>
 		<constant name="MIDI_MESSAGE_PROGRAM_CHANGE" value="12" enum="MidiMessageList">
+			MIDI program change message.
 		</constant>
 		<constant name="MIDI_MESSAGE_CHANNEL_PRESSURE" value="13" enum="MidiMessageList">
+			MIDI channel pressure message.
 		</constant>
 		<constant name="MIDI_MESSAGE_PITCH_BEND" value="14" enum="MidiMessageList">
+			MIDI pitch bend message.
 		</constant>
 		<constant name="OK" value="0" enum="Error">
 			Methods that return [enum Error] return [constant OK] when no error occurred. Note that many functions don't return an error code but will print error messages to standard output.
@@ -1304,88 +1317,112 @@
 			No hint for the edited property.
 		</constant>
 		<constant name="PROPERTY_HINT_RANGE" value="1" enum="PropertyHint">
-			Hints that the string is a range, defined as [code]"min,max"[/code] or [code]"min,max,step"[/code]. This is valid for integers and floats.
+			Hints that an integer or float property should be within a range specified via the hint string [code]"min,max"[/code] or [code]"min,max,step"[/code]. The hint string can optionally include [code]"allow_greater"[/code] and/or [code]"allow_lesser"[/code] to allow manual input going respectively above the max or below the min values. Example: [code]"-360,360,1,allow_greater,allow_lesser"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_EXP_RANGE" value="2" enum="PropertyHint">
-			Hints that the string is an exponential range, defined as [code]"min,max"[/code] or [code]"min,max,step"[/code]. This is valid for integers and floats.
+			Hints that an integer or float property should be within an exponential range specified via the hint string [code]"min,max"[/code] or [code]"min,max,step"[/code]. The hint string can optionally include [code]"allow_greater"[/code] and/or [code]"allow_lesser"[/code] to allow manual input going respectively above the max or below the min values. Example: [code]"0.01,100,0.01,allow_greater"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_ENUM" value="3" enum="PropertyHint">
-			Property hint for an enumerated value, like [code]"Hello,Something,Else"[/code]. This is valid for integer, float and string properties.
+			Hints that an integer, float or string property is an enumerated value to pick in a list specified via a hint string such as [code]"Hello,Something,Else"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_EXP_EASING" value="4" enum="PropertyHint">
+			Hints that a float property should be edited via an exponential easing function. The hint string can include [code]"attenuation"[/code] to flip the curve horizontally and/or [code]"inout"[/code] to also include in/out easing.
 		</constant>
 		<constant name="PROPERTY_HINT_LENGTH" value="5" enum="PropertyHint">
+			Deprecated hint, unused.
 		</constant>
 		<constant name="PROPERTY_HINT_KEY_ACCEL" value="7" enum="PropertyHint">
+			Deprecated hint, unused.
 		</constant>
 		<constant name="PROPERTY_HINT_FLAGS" value="8" enum="PropertyHint">
-			Property hint for a bitmask description. For example, for bits 0, 1, 2, 3 and 5, the hint could be something like [code]"Bit0,Bit1,Bit2,Bit3,,Bit5"[/code]. This is only valid for integer properties.
+			Hints that an integer property is a bitmask with named bit flags. For example, to allow toggling bits 0, 1, 2 and 4, the hint could be something like [code]"Bit0,Bit1,Bit2,,Bit4"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_LAYERS_2D_RENDER" value="9" enum="PropertyHint">
+			Hints that an integer property is a bitmask using the optionally named 2D render layers.
 		</constant>
 		<constant name="PROPERTY_HINT_LAYERS_2D_PHYSICS" value="10" enum="PropertyHint">
+			Hints that an integer property is a bitmask using the optionally named 2D physics layers.
 		</constant>
 		<constant name="PROPERTY_HINT_LAYERS_3D_RENDER" value="11" enum="PropertyHint">
+			Hints that an integer property is a bitmask using the optionally named 3D render layers.
 		</constant>
 		<constant name="PROPERTY_HINT_LAYERS_3D_PHYSICS" value="12" enum="PropertyHint">
+			Hints that an integer property is a bitmask using the optionally named 3D physics layers.
 		</constant>
 		<constant name="PROPERTY_HINT_FILE" value="13" enum="PropertyHint">
-			String property is a file, will pop up a file dialog when edited. Hint string can be a set of wildcards like [code]"*.doc"[/code].
+			Hints that a string property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_DIR" value="14" enum="PropertyHint">
-			String property is a directory, will pop up a file dialog when edited.
+			Hints that a string property is a path to a directory. Editing it will show a file dialog for picking the path.
 		</constant>
 		<constant name="PROPERTY_HINT_GLOBAL_FILE" value="15" enum="PropertyHint">
+			Hints that a string property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_GLOBAL_DIR" value="16" enum="PropertyHint">
+			Hints that a string property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path.
 		</constant>
 		<constant name="PROPERTY_HINT_RESOURCE_TYPE" value="17" enum="PropertyHint">
-			String property is a resource, will open the resource popup menu when edited.
+			Hints that a property is an instance of a [Resource]-derived type, optionally specified via the hint string (e.g. [code]"Texture"[/code]). Editing it will show a popup menu of valid resource types to instantiate.
 		</constant>
 		<constant name="PROPERTY_HINT_MULTILINE_TEXT" value="18" enum="PropertyHint">
+			Hints that a string property is text with line breaks. Editing it will show a text input field where line breaks can be typed.
 		</constant>
 		<constant name="PROPERTY_HINT_PLACEHOLDER_TEXT" value="19" enum="PropertyHint">
+			Hints that a string property should have a placeholder text visible on its input field, whenever the property is empty. The hint string is the placeholder text to use.
 		</constant>
 		<constant name="PROPERTY_HINT_COLOR_NO_ALPHA" value="20" enum="PropertyHint">
+			Hints that a color property should be edited without changing its alpha component, i.e. only R, G and B channels are edited.
 		</constant>
 		<constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSY" value="21" enum="PropertyHint">
-			Hints that the image is compressed using lossy compression.
+			Hints that an image is compressed using lossy compression.
 		</constant>
 		<constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS" value="22" enum="PropertyHint">
-			Hints that the image is compressed using lossless compression.
+			Hints that an image is compressed using lossless compression.
 		</constant>
 		<constant name="PROPERTY_USAGE_STORAGE" value="1" enum="PropertyUsageFlags">
-			Property will be used as storage (default).
+			The property is serialized and saved in the scene file (default).
 		</constant>
 		<constant name="PROPERTY_USAGE_EDITOR" value="2" enum="PropertyUsageFlags">
-			Property will be visible in editor (default).
+			The property is shown in the editor inspector (default).
 		</constant>
 		<constant name="PROPERTY_USAGE_NETWORK" value="4" enum="PropertyUsageFlags">
+			Deprecated usage flag, unused.
 		</constant>
 		<constant name="PROPERTY_USAGE_EDITOR_HELPER" value="8" enum="PropertyUsageFlags">
+			Deprecated usage flag, unused.
 		</constant>
 		<constant name="PROPERTY_USAGE_CHECKABLE" value="16" enum="PropertyUsageFlags">
+			The property can be checked in the editor inspector.
 		</constant>
 		<constant name="PROPERTY_USAGE_CHECKED" value="32" enum="PropertyUsageFlags">
+			The property is checked in the editor inspector.
 		</constant>
 		<constant name="PROPERTY_USAGE_INTERNATIONALIZED" value="64" enum="PropertyUsageFlags">
+			The property is a translatable string.
 		</constant>
 		<constant name="PROPERTY_USAGE_GROUP" value="128" enum="PropertyUsageFlags">
+			Used to group properties together in the editor.
 		</constant>
 		<constant name="PROPERTY_USAGE_CATEGORY" value="256" enum="PropertyUsageFlags">
+			Used to categorize properties together in the editor.
 		</constant>
 		<constant name="PROPERTY_USAGE_NO_INSTANCE_STATE" value="2048" enum="PropertyUsageFlags">
+			The property does not save its state in [PackedScene].
 		</constant>
 		<constant name="PROPERTY_USAGE_RESTART_IF_CHANGED" value="4096" enum="PropertyUsageFlags">
+			Editing the property prompts the user for restarting the editor.
 		</constant>
 		<constant name="PROPERTY_USAGE_SCRIPT_VARIABLE" value="8192" enum="PropertyUsageFlags">
+			The property is a script variable which should be serialized and saved in the scene file.
 		</constant>
 		<constant name="PROPERTY_USAGE_DEFAULT" value="7" enum="PropertyUsageFlags">
-			Default usage (storage and editor).
+			Default usage (storage, editor and network).
 		</constant>
 		<constant name="PROPERTY_USAGE_DEFAULT_INTL" value="71" enum="PropertyUsageFlags">
+			Default usage for translatable strings (storage, editor, network and internationalized).
 		</constant>
 		<constant name="PROPERTY_USAGE_NOEDITOR" value="5" enum="PropertyUsageFlags">
+			Default usage but without showing the property in the editor (storage, network).
 		</constant>
 		<constant name="METHOD_FLAG_NORMAL" value="1" enum="MethodFlags">
 			Flag for a normal method.
@@ -1394,23 +1431,25 @@
 			Flag for an editor method.
 		</constant>
 		<constant name="METHOD_FLAG_NOSCRIPT" value="4" enum="MethodFlags">
+			Deprecated method flag, unused.
 		</constant>
 		<constant name="METHOD_FLAG_CONST" value="8" enum="MethodFlags">
 			Flag for a constant method.
 		</constant>
 		<constant name="METHOD_FLAG_REVERSE" value="16" enum="MethodFlags">
+			Deprecated method flag, unused.
 		</constant>
 		<constant name="METHOD_FLAG_VIRTUAL" value="32" enum="MethodFlags">
 			Flag for a virtual method.
 		</constant>
 		<constant name="METHOD_FLAG_FROM_SCRIPT" value="64" enum="MethodFlags">
-			Flag for a method from a script.
+			Deprecated method flag, unused.
 		</constant>
 		<constant name="METHOD_FLAGS_DEFAULT" value="1" enum="MethodFlags">
 			Default method flags.
 		</constant>
 		<constant name="TYPE_NIL" value="0" enum="Variant.Type">
-			Variable is of type nil (only applied for [code]null[/code]).
+			Variable is of type [Nil] (only applied for [code]null[/code]).
 		</constant>
 		<constant name="TYPE_BOOL" value="1" enum="Variant.Type">
 			Variable is of type [bool].
@@ -1419,7 +1458,7 @@
 			Variable is of type [int].
 		</constant>
 		<constant name="TYPE_REAL" value="3" enum="Variant.Type">
-			Variable is of type [float]/real.
+			Variable is of type [float] (real).
 		</constant>
 		<constant name="TYPE_STRING" value="4" enum="Variant.Type">
 			Variable is of type [String].
@@ -1494,54 +1533,79 @@
 			Represents the size of the [enum Variant.Type] enum.
 		</constant>
 		<constant name="OP_EQUAL" value="0" enum="Variant.Operator">
+			Equality operator ([code]==[/code]).
 		</constant>
 		<constant name="OP_NOT_EQUAL" value="1" enum="Variant.Operator">
+			Inequality operator ([code]!=[/code]).
 		</constant>
 		<constant name="OP_LESS" value="2" enum="Variant.Operator">
+			Less than operator ([code]&lt;[/code]).
 		</constant>
 		<constant name="OP_LESS_EQUAL" value="3" enum="Variant.Operator">
+			Less than or equal operator ([code]&lt;=[/code]).
 		</constant>
 		<constant name="OP_GREATER" value="4" enum="Variant.Operator">
+			Greater than operator ([code]&gt;[/code]).
 		</constant>
 		<constant name="OP_GREATER_EQUAL" value="5" enum="Variant.Operator">
+			Greater than or equal operator ([code]&gt;=[/code]).
 		</constant>
 		<constant name="OP_ADD" value="6" enum="Variant.Operator">
+			Addition operator ([code]+[/code]).
 		</constant>
 		<constant name="OP_SUBTRACT" value="7" enum="Variant.Operator">
+			Subtraction operator ([code]-[/code]).
 		</constant>
 		<constant name="OP_MULTIPLY" value="8" enum="Variant.Operator">
+			Multiplication operator ([code]*[/code]).
 		</constant>
 		<constant name="OP_DIVIDE" value="9" enum="Variant.Operator">
+			Division operator ([code]/[/code]).
 		</constant>
 		<constant name="OP_NEGATE" value="10" enum="Variant.Operator">
+			Unary negation operator ([code]-[/code]).
 		</constant>
 		<constant name="OP_POSITIVE" value="11" enum="Variant.Operator">
+			Unary plus operator ([code]+[/code]).
 		</constant>
 		<constant name="OP_MODULE" value="12" enum="Variant.Operator">
+			Remainder/modulo operator ([code]%[/code]).
 		</constant>
 		<constant name="OP_STRING_CONCAT" value="13" enum="Variant.Operator">
+			String concatenation operator ([code]+[/code]).
 		</constant>
 		<constant name="OP_SHIFT_LEFT" value="14" enum="Variant.Operator">
+			Left shift operator ([code]&lt;&lt;[/code]).
 		</constant>
 		<constant name="OP_SHIFT_RIGHT" value="15" enum="Variant.Operator">
+			Right shift operator ([code]&gt;&gt;[/code]).
 		</constant>
 		<constant name="OP_BIT_AND" value="16" enum="Variant.Operator">
+			Bitwise AND operator ([code]&amp;[/code]).
 		</constant>
 		<constant name="OP_BIT_OR" value="17" enum="Variant.Operator">
+			Bitwise OR operator ([code]|[/code]).
 		</constant>
 		<constant name="OP_BIT_XOR" value="18" enum="Variant.Operator">
+			Bitwise XOR operator ([code]^[/code]).
 		</constant>
 		<constant name="OP_BIT_NEGATE" value="19" enum="Variant.Operator">
+			Bitwise NOT operator ([code]~[/code]).
 		</constant>
 		<constant name="OP_AND" value="20" enum="Variant.Operator">
+			Logical AND operator ([code]and[/code] or [code]&amp;&amp;[/code]).
 		</constant>
 		<constant name="OP_OR" value="21" enum="Variant.Operator">
+			Logical OR operator ([code]or[/code] or [code]||[/code]).
 		</constant>
 		<constant name="OP_XOR" value="22" enum="Variant.Operator">
+			Logical XOR operator (not implemented in GDScript).
 		</constant>
 		<constant name="OP_NOT" value="23" enum="Variant.Operator">
+			Logical NOT operator ([code]not[/code] or [code]![/code]).
 		</constant>
 		<constant name="OP_IN" value="24" enum="Variant.Operator">
+			Logical IN operator ([code]in[/code]).
 		</constant>
 		<constant name="OP_MAX" value="25" enum="Variant.Operator">
 			Represents the size of the [enum Variant.Operator] enum.