godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #73281 from Mickeon/doc-misc-oops 

Slightly tweak `@GlobalScope` & `GDScript`'s documentation
This commit is contained in:
Rémi Verschelde 2023-02-14 13:37:43 +01:00
parent c132636155 436bbfebe2
commit f9b043aad7
No known key found for this signature in database
GPG Key ID: C3336907360768E1
2 changed files with 50 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/classes/@GlobalScope.xml
View File

@ -803,7 +803,8 @@
Returns the result of [param base] raised to the power of [param exp].
In GDScript, this is the equivalent of the [code]**[/code] operator.
[codeblock]
pow(2, 5) # Returns 32
pow(2, 5) # Returns 32.0
pow(4, 1.5) # Returns 8.0
[/codeblock]
</description>
</method>
@ -1287,14 +1288,14 @@
Converts a formatted [param string] that was returned by [method var_to_str] to the original [Variant].
[codeblocks]
[gdscript]
var a = '{ "a": 1, "b": 2 }' # a is a String
var b = str_to_var(a) # b is a Dictionary
print(b["a"]) # Prints 1
var data = '{ "a": 1, "b": 2 }' # data is a String
var dict = str_to_var(data) # dict is a Dictionary
print(dict["a"]) # Prints 1
[/gdscript]
[csharp]
string a = "{ \"a\": 1, \"b\": 2 }"; // a is a string
var b = GD.StrToVar(a).AsGodotDictionary(); // b is a Dictionary
GD.Print(b["a"]); // Prints 1
string data = "{ \"a\": 1, \"b\": 2 }"; // data is a string
var dict = GD.StrToVar(data).AsGodotDictionary(); // dict is a Dictionary
GD.Print(dict["a"]); // Prints 1
[/csharp]
[/codeblocks]
</description>
@ -2272,7 +2273,7 @@
Command (on macOS) or Meta/Windows key mask.
</constant>
<constant name="KEY_MASK_CTRL" value="268435456" enum="KeyModifierMask" is_bitfield="true">
Ctrl key mask.
Control key mask.
</constant>
<constant name="KEY_MASK_KPAD" value="536870912" enum="KeyModifierMask" is_bitfield="true">
Keypad key mask.
@ -2293,10 +2294,10 @@
Middle mouse button.
</constant>
<constant name="MOUSE_BUTTON_WHEEL_UP" value="4" enum="MouseButton">
Mouse wheel up.
Mouse wheel scrolling up.
</constant>
<constant name="MOUSE_BUTTON_WHEEL_DOWN" value="5" enum="MouseButton">
Mouse wheel down.
Mouse wheel scrolling down.
</constant>
<constant name="MOUSE_BUTTON_WHEEL_LEFT" value="6" enum="MouseButton">
Mouse wheel left button (only present on some mice).
@ -2760,6 +2761,7 @@
Hints that a string property is a password, and every character is replaced with the secret character.
</constant>
<constant name="PROPERTY_HINT_MAX" value="37" enum="PropertyHint">
Represents the size of the [enum PropertyHint] enum.
</constant>
<constant name="PROPERTY_USAGE_NONE" value="0" enum="PropertyUsageFlags" is_bitfield="true">
The property is not stored, and does not display in the editor. This is the default for non-exported properties.

74
modules/gdscript/doc_classes/@GDScript.xml
View File

@ -4,7 +4,7 @@
Built-in GDScript functions.
</brief_description>
<description>
A list of GDScript-specific utility functions accessed in any script.
A list of GDScript-specific utility functions and annotations accessible from any script.
For the list of the global functions and constants see [@GlobalScope].
</description>
<tutorials>
@ -20,7 +20,7 @@
<description>
Returns a [Color] constructed from red ([param r8]), green ([param g8]), blue ([param b8]), and optionally alpha ([param a8]) integer channels, each divided by [code]255.0[/code] for their final value.
[codeblock]
var red = Color8(255, 0, 0) # Same as Color(1, 0, 0)
var red = Color8(255, 0, 0) # Same as Color(1, 0, 0).
var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2).
var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4).
[/codeblock]
@ -37,10 +37,10 @@
[codeblock]
# Imagine we always want speed to be between 0 and 20.
var speed = -10
assert(speed &lt; 20) # True, the program will continue
assert(speed &gt;= 0) # False, the program will stop
assert(speed &gt;= 0 and speed &lt; 20) # You can also combine the two conditional statements in one check
assert(speed &lt; 20, "the speed limit is 20") # Show a message
assert(speed &lt; 20) # True, the program will continue.
assert(speed &gt;= 0) # False, the program will stop.
assert(speed &gt;= 0 and speed &lt; 20) # You can also combine the two conditional statements in one check.
assert(speed &lt; 20, "the speed limit is 20") # Show a message.
[/codeblock]
</description>
</method>
@ -140,7 +140,7 @@
<param index="0" name="path" type="String" />
<description>
Returns a [Resource] from the filesystem located at the absolute [param path]. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use [method preload].
[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script.
[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script.
[codeblock]
# Load a scene called "main" located in the root of the project directory and cache it in a variable.
var main = load("res://main.tscn") # main will contain a PackedScene resource.
@ -155,7 +155,7 @@
<param index="0" name="path" type="String" />
<description>
Returns a [Resource] from the filesystem located at [param path]. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires [param path] to be a constant [String]. If you want to load a resource from a dynamic/variable path, use [method load].
[b]Note:[/b] Resource paths can be obtained by right clicking on a resource in the Assets Panel and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script.
[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script.
[codeblock]
# Create instance of a scene.
var diamond = preload("res://diamond.tscn").instantiate()
@ -259,10 +259,12 @@
<annotation name="@export">
<return type="void" />
<description>
Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property use the type hint notation.
Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property, use the type hint notation.
[codeblock]
@export var string = ""
@export var int_number = 5
@export var float_number: float = 5
@export var image : Image
[/codeblock]
</description>
</annotation>
@ -273,20 +275,20 @@
Define a new category for the following exported properties. This helps to organize properties in the Inspector dock.
See also [constant PROPERTY_USAGE_CATEGORY].
[codeblock]
@export_category("My Properties")
@export var number = 3
@export var string = ""
@export_category("Statistics")
@export var hp = 30
@export var speed = 1.25
[/codeblock]
[b]Note:[/b] Categories in the property list are supposed to indicate different base types, so the use of this annotation is not encouraged. See [annotation @export_group] and [annotation @export_subgroup] instead.
[b]Note:[/b] Categories in the Inspector dock's list usually divide properties coming from different classes (Node, Node2D, Sprite, etc.). For better clarity, it's recommended to use [annotation @export_group] and [annotation @export_subgroup], instead.
</description>
</annotation>
<annotation name="@export_color_no_alpha">
<return type="void" />
<description>
Export a [Color] property without transparency (its alpha fixed as [code]1.0[/code]).
Export a [Color] property without allowing its transparency ([member Color.a]) to be edited.
See also [constant PROPERTY_HINT_COLOR_NO_ALPHA].
[codeblock]
@export_color_no_alpha var modulate_color: Color
@export_color_no_alpha var dye_color : Color
[/codeblock]
</description>
</annotation>
@ -296,7 +298,7 @@
Export a [String] property as a path to a directory. The path will be limited to the project folder and its subfolders. See [annotation @export_global_dir] to allow picking from the entire filesystem.
See also [constant PROPERTY_HINT_DIR].
[codeblock]
@export_dir var sprite_folder: String
@export_dir var sprite_folder_path: String
[/codeblock]
</description>
</annotation>
@ -343,8 +345,8 @@
If [param filter] is provided, only matching files will be available for picking.
See also [constant PROPERTY_HINT_FILE].
[codeblock]
@export_file var sound_effect_file: String
@export_file("*.txt") var notes_file: String
@export_file var sound_effect_path: String
@export_file("*.txt") var notes_path: String
[/codeblock]
</description>
</annotation>
@ -436,10 +438,10 @@
<annotation name="@export_global_dir">
<return type="void" />
<description>
Export a [String] property as a path to a directory. The path can be picked from the entire filesystem. See [annotation @export_dir] to limit it to the project folder and its subfolders.
Export a [String] property as an absolute path to a directory. The path can be picked from the entire filesystem. See [annotation @export_dir] to limit it to the project folder and its subfolders.
See also [constant PROPERTY_HINT_GLOBAL_DIR].
[codeblock]
@export_global_dir var sprite_folder: String
@export_global_dir var sprite_folder_path: String
[/codeblock]
</description>
</annotation>
@ -447,12 +449,12 @@
<return type="void" />
<param index="0" name="filter" type="String" default="&quot;&quot;" />
<description>
Export a [String] property as a path to a file. The path can be picked from the entire filesystem. See [annotation @export_file] to limit it to the project folder and its subfolders.
Export a [String] property as an absolute path to a file. The path can be picked from the entire filesystem. See [annotation @export_file] to limit it to the project folder and its subfolders.
If [param filter] is provided, only matching files will be available for picking.
See also [constant PROPERTY_HINT_GLOBAL_FILE].
[codeblock]
@export_global_file var sound_effect_file: String
@export_global_file("*.txt") var notes_file: String
@export_global_file var sound_effect_path: String
@export_global_file("*.txt") var notes_path: String
[/codeblock]
</description>
</annotation>
@ -466,13 +468,13 @@
Groups cannot be nested, use [annotation @export_subgroup] to add subgroups within groups.
See also [constant PROPERTY_USAGE_GROUP].
[codeblock]
@export_group("My Properties")
@export var number = 3
@export var string = ""
@export_group("Racer Properties")
@export var nickname = "Nick"
@export var age = 26
@export_group("Prefixed Properties", "prefix_")
@export var prefix_number = 3
@export var prefix_string = ""
@export_group("Car Properties", "car_")
@export var car_label = "Speedy"
@export var car_number = 3
@export_group("", "")
@export var ungrouped_number = 3
@ -544,13 +546,13 @@
Define a new subgroup for the following exported properties. This helps to organize properties in the Inspector dock. Subgroups work exactly like groups, except they need a parent group to exist. See [annotation @export_group].
See also [constant PROPERTY_USAGE_SUBGROUP].
[codeblock]
@export_group("My Properties")
@export var number = 3
@export var string = ""
@export_group("Racer Properties")
@export var nickname = "Nick"
@export var age = 26
@export_subgroup("My Prefixed Properties", "prefix_")
@export var prefix_number = 3
@export var prefix_string = ""
@export_subgroup("Car Properties", "car_")
@export var car_label = "Speedy"
@export var car_number = 3
[/codeblock]
[b]Note:[/b] Subgroups cannot be nested, they only provide one extra level of depth. Just like the next group ends the previous group, so do the subsequent subgroups.
</description>
@ -571,7 +573,7 @@
<annotation name="@onready">
<return type="void" />
<description>
Mark the following property as assigned on [Node]'s ready state change. Values for these properties are not assigned immediately upon the node's creation, and instead are computed and stored right before [method Node._ready].
Mark the following property as assigned when the [Node] is ready. Values for these properties are not assigned immediately when the node is initialized ([method Object._init]), and instead are computed and stored right before [method Node._ready].
[codeblock]
@onready var character_name: Label = $Label
[/codeblock]