From 25037ce03241368a1bb9862b760c587208d3151d Mon Sep 17 00:00:00 2001 From: Micky Date: Fri, 6 Sep 2024 00:25:59 +0200 Subject: [PATCH] Clean up more `[b]Example:[/b]` lines from the class reference --- doc/classes/AnimatedSprite2D.xml | 2 +- doc/classes/AnimatedSprite3D.xml | 2 +- doc/classes/Area2D.xml | 4 ++-- doc/classes/Area3D.xml | 4 ++-- doc/classes/Button.xml | 6 +++--- doc/classes/CanvasItem.xml | 2 +- doc/classes/CharacterBody2D.xml | 2 +- doc/classes/EditorImportPlugin.xml | 2 +- doc/classes/EditorScenePostImport.xml | 2 +- doc/classes/EditorScript.xml | 2 +- doc/classes/EditorTranslationParserPlugin.xml | 3 +-- doc/classes/HTTPRequest.xml | 6 +++--- doc/classes/PopupMenu.xml | 3 +-- doc/classes/PrimitiveMesh.xml | 3 ++- doc/classes/SyntaxHighlighter.xml | 9 ++++----- doc/classes/TextEdit.xml | 1 - doc/classes/Window.xml | 3 +-- modules/gdscript/doc_classes/GDScript.xml | 3 +-- modules/regex/doc_classes/RegEx.xml | 4 ++-- 19 files changed, 29 insertions(+), 34 deletions(-) diff --git a/doc/classes/AnimatedSprite2D.xml b/doc/classes/AnimatedSprite2D.xml index 88e543591a07..cc1e9117f909 100644 --- a/doc/classes/AnimatedSprite2D.xml +++ b/doc/classes/AnimatedSprite2D.xml @@ -55,7 +55,7 @@ Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly. - [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]. + [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]: [codeblocks] [gdscript] var current_frame = animated_sprite.get_frame() diff --git a/doc/classes/AnimatedSprite3D.xml b/doc/classes/AnimatedSprite3D.xml index a466fc32ac91..1b1f58e5f4b5 100644 --- a/doc/classes/AnimatedSprite3D.xml +++ b/doc/classes/AnimatedSprite3D.xml @@ -54,7 +54,7 @@ Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly. - [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]. + [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]: [codeblocks] [gdscript] var current_frame = animated_sprite.get_frame() diff --git a/doc/classes/Area2D.xml b/doc/classes/Area2D.xml index 4ad5db2b6731..61a103f20daa 100644 --- a/doc/classes/Area2D.xml +++ b/doc/classes/Area2D.xml @@ -132,7 +132,7 @@ Emitted when a [Shape2D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer2D]. - [b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape2D] node from the shape index: [codeblocks] [gdscript] var other_shape_owner = area.shape_find_owner(area_shape_index) @@ -174,7 +174,7 @@ Emitted when a [Shape2D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody2D] or a [TileMap]. [TileMap]s are detected if their [TileSet] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer2D]. - [b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape2D] node from the shape index: [codeblocks] [gdscript] var body_shape_owner = body.shape_find_owner(body_shape_index) diff --git a/doc/classes/Area3D.xml b/doc/classes/Area3D.xml index 8eedd3cdf2a6..aac98593ff21 100644 --- a/doc/classes/Area3D.xml +++ b/doc/classes/Area3D.xml @@ -156,7 +156,7 @@ Emitted when a [Shape3D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer3D]. - [b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape3D] node from the shape index: [codeblocks] [gdscript] var other_shape_owner = area.shape_find_owner(area_shape_index) @@ -198,7 +198,7 @@ Emitted when a [Shape3D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody3D] or a [GridMap]. [GridMap]s are detected if their [MeshLibrary] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer3D]. - [b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape3D] node from the shape index: [codeblocks] [gdscript] var body_shape_owner = body.shape_find_owner(body_shape_index) diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index 68fb918904f3..5af2947997d0 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -5,13 +5,13 @@ [Button] is the standard themed button. It can contain text and an icon, and it will display them according to the current [Theme]. - [b]Example of creating a button and assigning an action when pressed by code:[/b] + [b]Example:[/b] Create a button and connect a method that will be called when the button is pressed: [codeblocks] [gdscript] func _ready(): var button = Button.new() button.text = "Click me" - button.pressed.connect(self._button_pressed) + button.pressed.connect(_button_pressed) add_child(button) func _button_pressed(): @@ -33,7 +33,7 @@ [/csharp] [/codeblocks] See also [BaseButton] which contains common properties and methods associated with this node. - [b]Note:[/b] Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions. + [b]Note:[/b] Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions. https://godotengine.org/asset-library/asset/2712 diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 0a0223c550c8..e21c79e2617c 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -333,7 +333,7 @@ Draws [param text] using the specified [param font] at the [param pos] (bottom-left corner using the baseline of the font). The text will have its color multiplied by [param modulate]. If [param width] 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] + [b]Example:[/b] Draw "Hello world", using the project's default font: [codeblocks] [gdscript] # If using this method in a script that redraws constantly, move the diff --git a/doc/classes/CharacterBody2D.xml b/doc/classes/CharacterBody2D.xml index ede4d63cfc87..30438be18b79 100644 --- a/doc/classes/CharacterBody2D.xml +++ b/doc/classes/CharacterBody2D.xml @@ -69,7 +69,7 @@ Returns a [KinematicCollision2D], which contains information about a collision that occurred during the last call to [method move_and_slide]. Since the body can collide several times in a single call to [method move_and_slide], you must specify the index of the collision in the range 0 to ([method get_slide_collision_count] - 1). - [b]Example usage:[/b] + [b]Example:[/b] Iterate through the collisions with a [code]for[/code] loop: [codeblocks] [gdscript] for i in get_slide_collision_count(): diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml index 28614b663186..3e048770627e 100644 --- a/doc/classes/EditorImportPlugin.xml +++ b/doc/classes/EditorImportPlugin.xml @@ -153,7 +153,7 @@ - This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. For example: + This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. [codeblocks] [gdscript] func _get_option_visibility(option, options): diff --git a/doc/classes/EditorScenePostImport.xml b/doc/classes/EditorScenePostImport.xml index 7325d31fc543..f8938c459cdc 100644 --- a/doc/classes/EditorScenePostImport.xml +++ b/doc/classes/EditorScenePostImport.xml @@ -5,7 +5,7 @@ Imported scenes can be automatically modified right after import by setting their [b]Custom Script[/b] Import property to a [code]tool[/code] script that inherits from this class. - The [method _post_import] callback receives the imported scene's root node and returns the modified version of the scene. Usage example: + The [method _post_import] callback receives the imported scene's root node and returns the modified version of the scene: [codeblocks] [gdscript] @tool # Needed so it runs in editor. diff --git a/doc/classes/EditorScript.xml b/doc/classes/EditorScript.xml index bd18852dbcfc..e342966fe888 100644 --- a/doc/classes/EditorScript.xml +++ b/doc/classes/EditorScript.xml @@ -6,7 +6,7 @@ Scripts extending this class and implementing its [method _run] method can be executed from the Script Editor's [b]File > Run[/b] menu option (or by pressing [kbd]Ctrl + Shift + X[/kbd]) while the editor is running. This is useful for adding custom in-editor functionality to Godot. For more complex additions, consider using [EditorPlugin]s instead. [b]Note:[/b] Extending scripts need to have [code]tool[/code] mode enabled. - [b]Example script:[/b] + [b]Example:[/b] Running the following script prints "Hello from the Godot Editor!": [codeblocks] [gdscript] @tool diff --git a/doc/classes/EditorTranslationParserPlugin.xml b/doc/classes/EditorTranslationParserPlugin.xml index a47a41594ef7..43bbeaefa799 100644 --- a/doc/classes/EditorTranslationParserPlugin.xml +++ b/doc/classes/EditorTranslationParserPlugin.xml @@ -69,8 +69,7 @@ msgidsContextPlural.Add(new Godot.Collections.Array{"Only with context", "a friendly context", ""}); [/csharp] [/codeblocks] - [b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [FileAccess] type. - For example: + [b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [FileAccess] type. For example: [codeblocks] [gdscript] func _parse_file(path, msgids, msgids_context_plural): diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index 6efa675a71e3..4cae4ef7def9 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -8,7 +8,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP. [b]Warning:[/b] See the notes and warnings on [HTTPClient] for limitations, especially regarding TLS security. [b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. - [b]Example of contacting a REST API and printing one of its returned fields:[/b] + [b]Example:[/b] Contact a REST API and print one of its returned fields: [codeblocks] [gdscript] func _ready(): @@ -80,7 +80,7 @@ } [/csharp] [/codeblocks] - [b]Example of loading and displaying an image using HTTPRequest:[/b] + [b]Example:/b] Load and display an image using [HTTPRequest]: [codeblocks] [gdscript] func _ready(): @@ -150,7 +150,7 @@ } [/csharp] [/codeblocks] - [b]Gzipped response bodies[/b]: HTTPRequest will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. + [b]Note:[/b] [HTTPRequest] nodes will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. $DOCS_URL/tutorials/networking/http_request_class.html diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 004bbe2286bb..e3c3cae4f82d 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -135,8 +135,6 @@ Adds a new multistate item with text [param label]. Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. The default value is defined by [param default_state]. An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. - [b]Note:[/b] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. - Example usage: [codeblock] func _ready(): add_multistate_item("Item", 3, 0) @@ -152,6 +150,7 @@ print("Third state") ) [/codeblock] + [b]Note:[/b] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index 58a8da12da6f..63e6b4d88a73 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -18,7 +18,8 @@ - Returns mesh arrays used to constitute surface of [Mesh]. The result can be passed to [method ArrayMesh.add_surface_from_arrays] to create a new surface. For example: + Returns the mesh arrays used to constitute the surface of this primitive mesh. + [b]Example:[/b] Pass the result to [method ArrayMesh.add_surface_from_arrays] to create a new surface: [codeblocks] [gdscript] var c = CylinderMesh.new() diff --git a/doc/classes/SyntaxHighlighter.xml b/doc/classes/SyntaxHighlighter.xml index 27cee26c50ad..de14e0e06f79 100644 --- a/doc/classes/SyntaxHighlighter.xml +++ b/doc/classes/SyntaxHighlighter.xml @@ -41,11 +41,11 @@ - Returns syntax highlighting data for a single line. If the line is not cached, calls [method _get_line_syntax_highlighting] to calculate the data. - The return [Dictionary] is column number to [Dictionary]. The column number notes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region, currently only the key "color" is supported. - [b]Example return:[/b] + Returns the syntax highlighting data for the line at index [param line]. If the line is not cached, calls [method _get_line_syntax_highlighting] first to calculate the data. + Each entry is a column number containing a nested [Dictionary]. The column number denotes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region. Currently only the key [code]"color"[/code] is supported. + [b]Example:[/b] Possibile return value. This means columns [code]0[/code] to [code]4[/code] should be red, and columns [code]5[/code] to the end of the line should be green: [codeblock] - var color_map = { + { 0: { "color": Color(1, 0, 0) }, @@ -54,7 +54,6 @@ } } [/codeblock] - This will color columns 0-4 red, and columns 5-eol in green. diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 6505e48fb9a3..533df6070f71 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -124,7 +124,6 @@ Starts an edit for multiple carets. The edit must be ended with [method end_multicaret_edit]. Multicaret edits can be used to edit text at multiple carets and delay merging the carets until the end, so the caret indexes aren't affected immediately. [method begin_multicaret_edit] and [method end_multicaret_edit] can be nested, and the merge will happen at the last [method end_multicaret_edit]. - Example usage: [codeblock] begin_complex_operation() begin_multicaret_edit() diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index ca155881c8ed..816cc341e037 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -720,8 +720,6 @@ Emitted when files are dragged from the OS file manager and dropped in the game window. The argument is a list of file paths. - Note that this method only works with native windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. - Example usage: [codeblock] func _ready(): get_viewport().files_dropped.connect(on_files_dropped) @@ -729,6 +727,7 @@ func on_files_dropped(files): print(files) [/codeblock] + [b]Note:[/b] This signal only works with native windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. diff --git a/modules/gdscript/doc_classes/GDScript.xml b/modules/gdscript/doc_classes/GDScript.xml index 5f7a7e2915f8..c3fa59dc23f6 100644 --- a/modules/gdscript/doc_classes/GDScript.xml +++ b/modules/gdscript/doc_classes/GDScript.xml @@ -16,11 +16,10 @@ Returns a new instance of the script. - For example: [codeblock] var MyClass = load("myclass.gd") var instance = MyClass.new() - assert(instance.get_script() == MyClass) + print(instance.get_script() == MyClass) # Prints true [/codeblock] diff --git a/modules/regex/doc_classes/RegEx.xml b/modules/regex/doc_classes/RegEx.xml index e12dc43b6ff9..66e7cd5a0bb7 100644 --- a/modules/regex/doc_classes/RegEx.xml +++ b/modules/regex/doc_classes/RegEx.xml @@ -34,14 +34,14 @@ print(result.get_string("digit")) # Would print 01 03 0 3f 42 [/codeblock] - [b]Example of splitting a string using a RegEx:[/b] + [b]Example:[/b] Split a string using a RegEx: [codeblock] var regex = RegEx.new() regex.compile("\\S+") # Negated whitespace character class. var results = [] for result in regex.search_all("One Two \n\tThree"): results.push_back(result.get_string()) - # The `results` array now contains "One", "Two", "Three". + # The `results` array now contains "One", "Two", and "Three". [/codeblock] [b]Note:[/b] Godot's regex implementation is based on the [url=https://www.pcre.org/]PCRE2[/url] library. You can view the full pattern reference [url=https://www.pcre.org/current/doc/html/pcre2pattern.html]here[/url]. [b]Tip:[/b] You can use [url=https://regexr.com/]Regexr[/url] to test regular expressions online.