summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/classes/Animation.xml4
-rw-r--r--doc/classes/Button.xml12
-rw-r--r--doc/classes/CanvasItem.xml11
-rw-r--r--doc/classes/EditorInterface.xml4
-rw-r--r--doc/classes/File.xml1
-rw-r--r--doc/classes/Font.xml1
-rw-r--r--doc/classes/JSON.xml3
-rw-r--r--doc/classes/JSONParseResult.xml10
-rw-r--r--doc/classes/String.xml5
-rw-r--r--doc/classes/TextEdit.xml3
-rw-r--r--doc/classes/Thread.xml3
-rw-r--r--doc/classes/TreeItem.xml12
-rwxr-xr-xdoc/tools/makerst.py118
13 files changed, 129 insertions, 58 deletions
diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml
index 09811d5617..68f0a630ef 100644
--- a/doc/classes/Animation.xml
+++ b/doc/classes/Animation.xml
@@ -7,10 +7,10 @@
An Animation resource contains data used to animate everything in the engine. Animations are divided into tracks, and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track.
[codeblock]
# This creates an animation that makes the node "Enemy" move to the right by
- # 100 pixels in 1 second.
+ # 100 pixels in 0.5 seconds.
var animation = Animation.new()
var track_index = animation.add_track(Animation.TYPE_VALUE)
- animation.track_set_path(track_index, "Enemy:position.x")
+ animation.track_set_path(track_index, "Enemy:position:x")
animation.track_insert_key(track_index, 0.0, 0)
animation.track_insert_key(track_index, 0.5, 100)
[/codeblock]
diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml
index 675441d842..de05cfcd13 100644
--- a/doc/classes/Button.xml
+++ b/doc/classes/Button.xml
@@ -5,6 +5,18 @@
</brief_description>
<description>
Button is the standard themed button. It can contain text and an icon, and will display them according to the current [Theme].
+ [b]Example of creating a button and assigning an action when pressed by code:[/b]
+ [codeblock]
+ func _ready():
+ var button = Button.new()
+ button.text = "Click me"
+ button.connect("pressed", self, "_button_pressed")
+ add_child(button)
+
+ func _button_pressed():
+ print("Hello world!")
+ [/codeblock]
+ Buttons (like all Control nodes) can also be created in the editor, but some situations may require creating them from code.
</description>
<tutorials>
</tutorials>
diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml
index cac4d6f36e..899988022f 100644
--- a/doc/classes/CanvasItem.xml
+++ b/doc/classes/CanvasItem.xml
@@ -316,7 +316,16 @@
<argument index="4" name="clip_w" type="int" default="-1">
</argument>
<description>
- Draws a string using a custom font.
+ Draws [code]text[/code] using the specified [code]font[/code] at the [code]position[/code] (top-left corner). The text will have its color multiplied by [code]modulate[/code]. If [code]clip_w[/code] is greater than or equal to 0, the text will be clipped if it exceeds the specified width.
+ [b]Example using the default project font:[/b]
+ [codeblock]
+ # If using this method in a script that redraws constantly, move the
+ # `default_font` declaration to a member variable assigned in `_ready()`
+ # so the Control is only created once.
+ var default_font = Control.new().get_font("font")
+ draw_string(default_font, Vector2(64, 64), "Hello world")
+ [/codeblock]
+ See also [method Font.draw].
</description>
</method>
<method name="draw_style_box">
diff --git a/doc/classes/EditorInterface.xml b/doc/classes/EditorInterface.xml
index 8b2b9c9350..9da36b51f9 100644
--- a/doc/classes/EditorInterface.xml
+++ b/doc/classes/EditorInterface.xml
@@ -51,8 +51,8 @@
<return type="Control">
</return>
<description>
- Returns the editor's [Viewport] instance.
- [b]Note:[/b] This returns the main editor viewport containing the whole editor, not the 2D or 3D viewports specifically.
+ Returns the main editor control. Use this as a parent for main screens.
+ [b]Note:[/b] This returns the main editor control containing the whole editor, not the 2D or 3D viewports specifically.
</description>
</method>
<method name="get_file_system_dock">
diff --git a/doc/classes/File.xml b/doc/classes/File.xml
index 20bc39ef1f..d91203d91f 100644
--- a/doc/classes/File.xml
+++ b/doc/classes/File.xml
@@ -257,6 +257,7 @@
</argument>
<description>
Opens an encrypted file in write or read mode. You need to pass a binary key to encrypt/decrypt it.
+ [b]Note:[/b] The provided key must be 32 bytes long.
</description>
</method>
<method name="open_encrypted_with_pass">
diff --git a/doc/classes/Font.xml b/doc/classes/Font.xml
index 30b8c1fe76..ce6a25e191 100644
--- a/doc/classes/Font.xml
+++ b/doc/classes/Font.xml
@@ -26,6 +26,7 @@
</argument>
<description>
Draw [code]string[/code] into a canvas item using the font at a given position, with [code]modulate[/code] color, and optionally clipping the width. [code]position[/code] specifies the baseline, not the top. To draw from the top, [i]ascent[/i] must be added to the Y axis.
+ See also [method CanvasItem.draw_string].
</description>
</method>
<method name="draw_char" qualifiers="const">
diff --git a/doc/classes/JSON.xml b/doc/classes/JSON.xml
index 7bd2edcb1c..2e837dea1d 100644
--- a/doc/classes/JSON.xml
+++ b/doc/classes/JSON.xml
@@ -15,7 +15,7 @@
<argument index="0" name="json" type="String">
</argument>
<description>
- Parses a JSON encoded string and returns a [JSONParseResult] containing the result.
+ Parses a JSON-encoded string and returns a [JSONParseResult] containing the result.
</description>
</method>
<method name="print">
@@ -29,6 +29,7 @@
</argument>
<description>
Converts a [Variant] var to JSON text and returns the result. Useful for serializing data to store or send over the network.
+ [b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, converting a Variant to JSON text will convert all numerical values to [float] types.
</description>
</method>
</methods>
diff --git a/doc/classes/JSONParseResult.xml b/doc/classes/JSONParseResult.xml
index 4444e08593..4dbceb35e9 100644
--- a/doc/classes/JSONParseResult.xml
+++ b/doc/classes/JSONParseResult.xml
@@ -15,21 +15,21 @@
The error type if the JSON source was not successfully parsed. See the [enum Error] constants.
</member>
<member name="error_line" type="int" setter="set_error_line" getter="get_error_line" default="-1">
- The line number where the error occurred if JSON source was not successfully parsed.
+ The line number where the error occurred if the JSON source was not successfully parsed.
</member>
<member name="error_string" type="String" setter="set_error_string" getter="get_error_string" default="&quot;&quot;">
- The error message if JSON source was not successfully parsed. See the [enum Error] constants.
+ The error message if the JSON source was not successfully parsed. See the [enum Error] constants.
</member>
<member name="result" type="Variant" setter="set_result" getter="get_result">
- A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with braces ([code][][/code]), an [Array] will be returned.
- [b]Note:[/b] The JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to float types.
+ A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with brackets ([code][][/code]), an [Array] will be returned.
+ [b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, parsing a JSON text will convert all numerical values to [float] types.
[b]Note:[/b] JSON objects do not preserve key order like Godot dictionaries, thus, you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements:
[codeblock]
var p = JSON.parse('["hello", "world", "!"]')
if typeof(p.result) == TYPE_ARRAY:
print(p.result[0]) # Prints "hello"
else:
- print("unexpected results")
+ push_error("Unexpected results.")
[/codeblock]
</member>
</members>
diff --git a/doc/classes/String.xml b/doc/classes/String.xml
index 7e55f8bd9a..ded64761d0 100644
--- a/doc/classes/String.xml
+++ b/doc/classes/String.xml
@@ -895,8 +895,8 @@
<argument index="2" name="maxsplit" type="int" default="0">
</argument>
<description>
- Splits the string by a [code]delimiter[/code] string and returns an array of the substrings.
- If [code]maxsplit[/code] is specified, it defines the number of splits to do from the left up to [code]maxsplit[/code]. The default value of 0 means that all items are split.
+ Splits the string by a [code]delimiter[/code] string and returns an array of the substrings. The [code]delimiter[/code] can be of any length.
+ If [code]maxsplit[/code] is specified, it defines the number of splits to do from the left up to [code]maxsplit[/code]. The default value of [code]0[/code] means that all items are split.
Example:
[codeblock]
var some_string = "One,Two,Three,Four"
@@ -905,6 +905,7 @@
print(some_array[0]) # Prints "One"
print(some_array[1]) # Prints "Two,Three,Four"
[/codeblock]
+ If you need to split strings with more complex rules, use the [RegEx] class instead.
</description>
</method>
<method name="split_floats">
diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml
index b7240655af..d4abac15c0 100644
--- a/doc/classes/TextEdit.xml
+++ b/doc/classes/TextEdit.xml
@@ -430,6 +430,9 @@
<member name="v_scroll_speed" type="float" setter="set_v_scroll_speed" getter="get_v_scroll_speed" default="80.0">
Vertical scroll sensitivity.
</member>
+ <member name="virtual_keyboard_enabled" type="bool" setter="set_virtual_keyboard_enabled" getter="is_virtual_keyboard_enabled" default="true">
+ If [code]true[/code], the native virtual keyboard is shown when focused on platforms that support it.
+ </member>
<member name="wrap_enabled" type="bool" setter="set_wrap_enabled" getter="is_wrap_enabled" default="false">
If [code]true[/code], enables text wrapping when it goes beyond the edge of what is visible.
</member>
diff --git a/doc/classes/Thread.xml b/doc/classes/Thread.xml
index 4d6e89fa6f..5c63d01322 100644
--- a/doc/classes/Thread.xml
+++ b/doc/classes/Thread.xml
@@ -7,7 +7,8 @@
A unit of execution in a process. Can run methods on [Object]s simultaneously. The use of synchronization via [Mutex] or [Semaphore] is advised if working with shared objects.
</description>
<tutorials>
- <link>https://docs.godotengine.org/en/latest/tutorials/threads/using_multiple_threads.html</link>
+ <link title="Using multiple threads">https://docs.godotengine.org/en/latest/tutorials/threads/using_multiple_threads.html</link>
+ <link title="Thread-safe APIs">https://docs.godotengine.org/en/latest/tutorials/threads/thread_safe_apis.html</link>
</tutorials>
<methods>
<method name="get_id" qualifiers="const">
diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml
index 126d6b4180..22e643a51d 100644
--- a/doc/classes/TreeItem.xml
+++ b/doc/classes/TreeItem.xml
@@ -118,7 +118,7 @@
<return type="TreeItem">
</return>
<description>
- Returns the TreeItem's child items.
+ Returns the TreeItem's first child item or a null object if there is none.
</description>
</method>
<method name="get_custom_bg_color" qualifiers="const">
@@ -196,7 +196,7 @@
<return type="TreeItem">
</return>
<description>
- Returns the next TreeItem in the tree.
+ Returns the next TreeItem in the tree or a null object if there is none.
</description>
</method>
<method name="get_next_visible">
@@ -205,7 +205,7 @@
<argument index="0" name="wrap" type="bool" default="false">
</argument>
<description>
- Returns the next visible TreeItem in the tree.
+ Returns the next visible TreeItem in the tree or a null object if there is none.
If [code]wrap[/code] is enabled, the method will wrap around to the first visible element in the tree when called on the last visible element, otherwise it returns [code]null[/code].
</description>
</method>
@@ -213,14 +213,14 @@
<return type="TreeItem">
</return>
<description>
- Returns the parent TreeItem.
+ Returns the parent TreeItem or a null object if there is none.
</description>
</method>
<method name="get_prev">
<return type="TreeItem">
</return>
<description>
- Returns the previous TreeItem in the tree.
+ Returns the previous TreeItem in the tree or a null object if there is none.
</description>
</method>
<method name="get_prev_visible">
@@ -229,7 +229,7 @@
<argument index="0" name="wrap" type="bool" default="false">
</argument>
<description>
- Returns the previous visible TreeItem in the tree.
+ Returns the previous visible TreeItem in the tree or a null object if there is none.
If [code]wrap[/code] is enabled, the method will wrap around to the last visible element in the tree when called on the first visible element, otherwise it returns [code]null[/code].
</description>
</method>
diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py
index c0bba38799..b594f652b3 100755
--- a/doc/tools/makerst.py
+++ b/doc/tools/makerst.py
@@ -565,6 +565,8 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S
index += 1
+ f.write(make_footer())
+
def escape_rst(text, until_pos=-1): # type: (str) -> str
# Escape \ character, otherwise it ends up as an escape character in rst
@@ -600,6 +602,43 @@ def escape_rst(text, until_pos=-1): # type: (str) -> str
return text
+def format_codeblock(code_type, post_text, indent_level, state): # types: str, str, int, state
+ end_pos = post_text.find("[/" + code_type + "]")
+ if end_pos == -1:
+ print_error("[" + code_type + "] without a closing tag, file: {}".format(state.current_class), state)
+ return None
+
+ code_text = post_text[len("[" + code_type + "]") : end_pos]
+ post_text = post_text[end_pos:]
+
+ # Remove extraneous tabs
+ code_pos = 0
+ while True:
+ code_pos = code_text.find("\n", code_pos)
+ if code_pos == -1:
+ break
+
+ to_skip = 0
+ while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == "\t":
+ to_skip += 1
+
+ if to_skip > indent_level:
+ print_error(
+ "Four spaces should be used for indentation within ["
+ + code_type
+ + "], file: {}".format(state.current_class),
+ state,
+ )
+
+ if len(code_text[code_pos + to_skip + 1 :]) == 0:
+ code_text = code_text[:code_pos] + "\n"
+ code_pos += 1
+ else:
+ code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1 :]
+ code_pos += 5 - to_skip
+ return ["\n[" + code_type + "]" + code_text + post_text, len("\n[" + code_type + "]" + code_text)]
+
+
def rstize_text(text, state): # type: (str, State) -> str
# Linebreak + tabs in the XML should become two line breaks unless in a "codeblock"
pos = 0
@@ -616,43 +655,17 @@ def rstize_text(text, state): # type: (str, State) -> str
post_text = text[pos + 1 :]
# Handle codeblocks
- if post_text.startswith("[codeblock]"):
- end_pos = post_text.find("[/codeblock]")
- if end_pos == -1:
- print_error("[codeblock] without a closing tag, file: {}".format(state.current_class), state)
+ if (
+ post_text.startswith("[codeblock]")
+ or post_text.startswith("[gdscript]")
+ or post_text.startswith("[csharp]")
+ ):
+ block_type = post_text[1:].split("]")[0]
+ result = format_codeblock(block_type, post_text, indent_level, state)
+ if result is None:
return ""
-
- code_text = post_text[len("[codeblock]") : end_pos]
- post_text = post_text[end_pos:]
-
- # Remove extraneous tabs
- code_pos = 0
- while True:
- code_pos = code_text.find("\n", code_pos)
- if code_pos == -1:
- break
-
- to_skip = 0
- while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == "\t":
- to_skip += 1
-
- if to_skip > indent_level:
- print_error(
- "Four spaces should be used for indentation within [codeblock], file: {}".format(
- state.current_class
- ),
- state,
- )
-
- if len(code_text[code_pos + to_skip + 1 :]) == 0:
- code_text = code_text[:code_pos] + "\n"
- code_pos += 1
- else:
- code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1 :]
- code_pos += 5 - to_skip
-
- text = pre_text + "\n[codeblock]" + code_text + post_text
- pos += len("\n[codeblock]" + code_text)
+ text = pre_text + result[0]
+ pos += result[1]
# Handle normal text
else:
@@ -697,7 +710,7 @@ def rstize_text(text, state): # type: (str, State) -> str
else: # command
cmd = tag_text
space_pos = tag_text.find(" ")
- if cmd == "/codeblock":
+ if cmd == "/codeblock" or cmd == "/gdscript" or cmd == "/csharp":
tag_text = ""
tag_depth -= 1
inside_code = False
@@ -813,6 +826,20 @@ def rstize_text(text, state): # type: (str, State) -> str
tag_depth += 1
tag_text = "\n::\n"
inside_code = True
+ elif cmd == "gdscript":
+ tag_depth += 1
+ tag_text = "\n .. code-tab:: gdscript GDScript\n"
+ inside_code = True
+ elif cmd == "csharp":
+ tag_depth += 1
+ tag_text = "\n .. code-tab:: csharp\n"
+ inside_code = True
+ elif cmd == "codeblocks":
+ tag_depth += 1
+ tag_text = "\n.. tabs::"
+ elif cmd == "/codeblocks":
+ tag_depth -= 1
+ tag_text = ""
elif cmd == "br":
# Make a new paragraph instead of a linebreak, rst is not so linebreak friendly
tag_text = "\n\n"
@@ -995,7 +1022,10 @@ def make_method_signature(
out += " **)**"
if isinstance(method_def, MethodDef) and method_def.qualifiers is not None:
- out += " " + method_def.qualifiers
+ # Use substitutions for abbreviations. This is used to display tooltips on hover.
+ # See `make_footer()` for descriptions.
+ for qualifier in method_def.qualifiers.split():
+ out += " |" + qualifier + "|"
return ret_type, out
@@ -1004,6 +1034,18 @@ def make_heading(title, underline): # type: (str, str) -> str
return title + "\n" + (underline * len(title)) + "\n\n"
+def make_footer(): # type: () -> str
+ # Generate reusable abbreviation substitutions.
+ # This way, we avoid bloating the generated rST with duplicate abbreviations.
+ # fmt: off
+ return (
+ ".. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`\n"
+ ".. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`\n"
+ ".. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`"
+ )
+ # fmt: on
+
+
def make_url(link): # type: (str) -> str
match = GODOT_DOCS_PATTERN.search(link)
if match:
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-13 18:35:19 +0000