From af28f87791ac4aed15d8f869876296febf5d5b58 Mon Sep 17 00:00:00 2001 From: Danil Alexeev Date: Mon, 12 Feb 2024 16:55:02 +0300 Subject: [PATCH] Documentation: Add support for deprecated/experimental messages --- core/doc_data.h | 110 +- doc/class.xsd | 21 + doc/classes/@GlobalScope.xml | 15 +- doc/classes/AStarGrid2D.xml | 3 +- doc/classes/AnimatedTexture.xml | 3 +- doc/classes/AnimationPlayer.xml | 33 +- doc/classes/AnimationTree.xml | 15 +- doc/classes/CollisionShape3D.xml | 4 +- doc/classes/Control.xml | 4 +- doc/classes/EditorPlugin.xml | 6 +- doc/classes/EditorScript.xml | 3 +- doc/classes/GraphEdit.xml | 2 +- doc/classes/GraphElement.xml | 2 +- doc/classes/GraphNode.xml | 2 +- doc/classes/HTTPClient.xml | 8 +- doc/classes/InputEventJoypadButton.xml | 4 +- doc/classes/LightmapGIData.xml | 3 +- doc/classes/MultiMesh.xml | 12 +- doc/classes/NavigationAgent2D.xml | 2 +- doc/classes/NavigationAgent3D.xml | 2 +- doc/classes/NavigationLink2D.xml | 2 +- doc/classes/NavigationLink3D.xml | 2 +- doc/classes/NavigationMesh.xml | 2 +- doc/classes/NavigationMeshGenerator.xml | 4 +- .../NavigationMeshSourceGeometryData2D.xml | 2 +- .../NavigationMeshSourceGeometryData3D.xml | 2 +- doc/classes/NavigationObstacle2D.xml | 2 +- doc/classes/NavigationObstacle3D.xml | 2 +- .../NavigationPathQueryParameters2D.xml | 2 +- .../NavigationPathQueryParameters3D.xml | 2 +- doc/classes/NavigationPathQueryResult2D.xml | 2 +- doc/classes/NavigationPathQueryResult3D.xml | 2 +- doc/classes/NavigationPolygon.xml | 5 +- doc/classes/NavigationRegion2D.xml | 5 +- doc/classes/NavigationRegion3D.xml | 5 +- doc/classes/NavigationServer2D.xml | 2 +- doc/classes/NavigationServer3D.xml | 6 +- doc/classes/Node.xml | 4 +- doc/classes/RenderingDevice.xml | 78 +- doc/classes/RenderingServer.xml | 22 +- doc/classes/Resource.xml | 8 +- doc/classes/ScriptLanguageExtension.xml | 3 +- doc/classes/ShapeCast3D.xml | 4 +- doc/classes/Skeleton3D.xml | 3 +- doc/classes/SkeletonIK3D.xml | 3 +- doc/classes/SkeletonModification2D.xml | 2 +- doc/classes/SkeletonModification2DCCDIK.xml | 2 +- doc/classes/SkeletonModification2DFABRIK.xml | 2 +- doc/classes/SkeletonModification2DJiggle.xml | 2 +- doc/classes/SkeletonModification2DLookAt.xml | 2 +- .../SkeletonModification2DPhysicalBones.xml | 2 +- .../SkeletonModification2DStackHolder.xml | 2 +- .../SkeletonModification2DTwoBoneIK.xml | 2 +- doc/classes/SkeletonModificationStack2D.xml | 2 +- doc/classes/StreamPeerGZIP.xml | 2 +- doc/classes/SubViewportContainer.xml | 2 +- doc/classes/SurfaceTool.xml | 3 +- doc/classes/TextureRect.xml | 2 +- doc/classes/TileMap.xml | 7 +- doc/classes/TreeItem.xml | 3 +- doc/classes/Viewport.xml | 3 +- doc/classes/Window.xml | 3 +- doc/classes/XRInterface.xml | 12 +- doc/tools/make_rst.py | 76 +- editor/doc_tools.cpp | 103 +- editor/editor_help.cpp | 1162 ++++++++++------- editor/editor_help.h | 8 +- modules/gdscript/doc_classes/@GDScript.xml | 3 +- modules/gdscript/editor/gdscript_docgen.cpp | 16 + modules/gdscript/gdscript_parser.cpp | 20 +- modules/gdscript/gdscript_parser.h | 4 + modules/gltf/doc_classes/GLTFDocument.xml | 2 +- modules/gltf/doc_classes/GLTFPhysicsBody.xml | 2 +- modules/gridmap/doc_classes/GridMap.xml | 4 +- .../doc_classes/SceneReplicationConfig.xml | 12 +- 75 files changed, 1161 insertions(+), 734 deletions(-) diff --git a/core/doc_data.h b/core/doc_data.h index 45463f59312f..04bd55eabae9 100644 --- a/core/doc_data.h +++ b/core/doc_data.h @@ -114,7 +114,9 @@ class DocData { String qualifiers; String description; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; Vector arguments; Vector errors_returned; String keywords; @@ -172,6 +174,7 @@ class DocData { doc.description = p_dict["description"]; } +#ifndef DISABLE_DEPRECATED if (p_dict.has("is_deprecated")) { doc.is_deprecated = p_dict["is_deprecated"]; } @@ -179,6 +182,17 @@ class DocData { if (p_dict.has("is_experimental")) { doc.is_experimental = p_dict["is_experimental"]; } +#endif + + if (p_dict.has("deprecated")) { + doc.is_deprecated = true; + doc.deprecated_message = p_dict["deprecated"]; + } + + if (p_dict.has("experimental")) { + doc.is_experimental = true; + doc.experimental_message = p_dict["experimental"]; + } Array arguments; if (p_dict.has("arguments")) { @@ -226,9 +240,13 @@ class DocData { dict["description"] = p_doc.description; } - dict["is_deprecated"] = p_doc.is_deprecated; + if (p_doc.is_deprecated) { + dict["deprecated"] = p_doc.deprecated_message; + } - dict["is_experimental"] = p_doc.is_experimental; + if (p_doc.is_experimental) { + dict["experimental"] = p_doc.experimental_message; + } if (!p_doc.keywords.is_empty()) { dict["keywords"] = p_doc.keywords; @@ -262,7 +280,9 @@ class DocData { bool is_bitfield = false; String description; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; String keywords; bool operator<(const ConstantDoc &p_const) const { return name < p_const.name; @@ -293,6 +313,7 @@ class DocData { doc.description = p_dict["description"]; } +#ifndef DISABLE_DEPRECATED if (p_dict.has("is_deprecated")) { doc.is_deprecated = p_dict["is_deprecated"]; } @@ -300,6 +321,17 @@ class DocData { if (p_dict.has("is_experimental")) { doc.is_experimental = p_dict["is_experimental"]; } +#endif + + if (p_dict.has("deprecated")) { + doc.is_deprecated = true; + doc.deprecated_message = p_dict["deprecated"]; + } + + if (p_dict.has("experimental")) { + doc.is_experimental = true; + doc.experimental_message = p_dict["experimental"]; + } if (p_dict.has("keywords")) { doc.keywords = p_dict["keywords"]; @@ -329,9 +361,13 @@ class DocData { dict["description"] = p_doc.description; } - dict["is_deprecated"] = p_doc.is_deprecated; + if (p_doc.is_deprecated) { + dict["deprecated"] = p_doc.deprecated_message; + } - dict["is_experimental"] = p_doc.is_experimental; + if (p_doc.is_experimental) { + dict["experimental"] = p_doc.experimental_message; + } if (!p_doc.keywords.is_empty()) { dict["keywords"] = p_doc.keywords; @@ -352,7 +388,9 @@ class DocData { bool overridden = false; String overrides; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; String keywords; bool operator<(const PropertyDoc &p_prop) const { return name.naturalcasecmp_to(p_prop.name) < 0; @@ -399,6 +437,7 @@ class DocData { doc.overrides = p_dict["overrides"]; } +#ifndef DISABLE_DEPRECATED if (p_dict.has("is_deprecated")) { doc.is_deprecated = p_dict["is_deprecated"]; } @@ -406,6 +445,17 @@ class DocData { if (p_dict.has("is_experimental")) { doc.is_experimental = p_dict["is_experimental"]; } +#endif + + if (p_dict.has("deprecated")) { + doc.is_deprecated = true; + doc.deprecated_message = p_dict["deprecated"]; + } + + if (p_dict.has("experimental")) { + doc.is_experimental = true; + doc.experimental_message = p_dict["experimental"]; + } if (p_dict.has("keywords")) { doc.keywords = p_dict["keywords"]; @@ -451,9 +501,13 @@ class DocData { dict["overrides"] = p_doc.overrides; } - dict["is_deprecated"] = p_doc.is_deprecated; + if (p_doc.is_deprecated) { + dict["deprecated"] = p_doc.deprecated_message; + } - dict["is_experimental"] = p_doc.is_experimental; + if (p_doc.is_experimental) { + dict["experimental"] = p_doc.experimental_message; + } if (!p_doc.keywords.is_empty()) { dict["keywords"] = p_doc.keywords; @@ -571,7 +625,9 @@ class DocData { struct EnumDoc { String description; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; static EnumDoc from_dict(const Dictionary &p_dict) { EnumDoc doc; @@ -579,6 +635,7 @@ class DocData { doc.description = p_dict["description"]; } +#ifndef DISABLE_DEPRECATED if (p_dict.has("is_deprecated")) { doc.is_deprecated = p_dict["is_deprecated"]; } @@ -586,6 +643,17 @@ class DocData { if (p_dict.has("is_experimental")) { doc.is_experimental = p_dict["is_experimental"]; } +#endif + + if (p_dict.has("deprecated")) { + doc.is_deprecated = true; + doc.deprecated_message = p_dict["deprecated"]; + } + + if (p_dict.has("experimental")) { + doc.is_experimental = true; + doc.experimental_message = p_dict["experimental"]; + } return doc; } @@ -596,9 +664,13 @@ class DocData { dict["description"] = p_doc.description; } - dict["is_deprecated"] = p_doc.is_deprecated; + if (p_doc.is_deprecated) { + dict["deprecated"] = p_doc.deprecated_message; + } - dict["is_experimental"] = p_doc.is_experimental; + if (p_doc.is_experimental) { + dict["experimental"] = p_doc.experimental_message; + } return dict; } @@ -621,7 +693,9 @@ class DocData { Vector annotations; Vector theme_properties; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; bool is_script_doc = false; String script_path; bool operator<(const ClassDoc &p_class) const { @@ -730,6 +804,7 @@ class DocData { doc.theme_properties.push_back(ThemeItemDoc::from_dict(theme_properties[i])); } +#ifndef DISABLE_DEPRECATED if (p_dict.has("is_deprecated")) { doc.is_deprecated = p_dict["is_deprecated"]; } @@ -737,6 +812,17 @@ class DocData { if (p_dict.has("is_experimental")) { doc.is_experimental = p_dict["is_experimental"]; } +#endif + + if (p_dict.has("deprecated")) { + doc.is_deprecated = true; + doc.deprecated_message = p_dict["deprecated"]; + } + + if (p_dict.has("experimental")) { + doc.is_experimental = true; + doc.experimental_message = p_dict["experimental"]; + } if (p_dict.has("is_script_doc")) { doc.is_script_doc = p_dict["is_script_doc"]; @@ -847,9 +933,13 @@ class DocData { dict["theme_properties"] = theme_properties; } - dict["is_deprecated"] = p_doc.is_deprecated; + if (p_doc.is_deprecated) { + dict["deprecated"] = p_doc.deprecated_message; + } - dict["is_experimental"] = p_doc.is_experimental; + if (p_doc.is_experimental) { + dict["experimental"] = p_doc.experimental_message; + } dict["is_script_doc"] = p_doc.is_script_doc; diff --git a/doc/class.xsd b/doc/class.xsd index 330fd214c0c6..f0e124105322 100644 --- a/doc/class.xsd +++ b/doc/class.xsd @@ -99,8 +99,12 @@ + + + + @@ -122,8 +126,12 @@ + + + + @@ -152,8 +160,12 @@ + + + + @@ -170,8 +182,12 @@ + + + + @@ -279,8 +295,13 @@ + + + + + diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 5736a97a7378..4cf5a88dd780 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -2889,8 +2889,7 @@ [/codeblocks] [b]Note:[/b] The trailing colon is required for properly detecting built-in types. - - [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. + Hints that an object is too big to be sent via the debugger. @@ -2904,9 +2903,7 @@ Hints that a [String] property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the entire filesystem. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. See also [member FileDialog.filters]. - - Hints that an [int] property is an object ID. - [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. + Hints that an [int] property is a pointer. Used by GDExtension. @@ -2977,9 +2974,7 @@ If this property is modified, all inspector fields will be refreshed. - - Signifies a default value from a placeholder script instance. - [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. + The property is an enum, i.e. it only takes named integer constants from its associated enumeration. @@ -3008,9 +3003,7 @@ Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row. - - When loading, the resource for this property can be set at the end of loading. - [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. + When this property is a [Resource] and base object is a [Node], a resource instance will be automatically created whenever the node is created in the editor. diff --git a/doc/classes/AStarGrid2D.xml b/doc/classes/AStarGrid2D.xml index 776423311628..4501bec314c5 100644 --- a/doc/classes/AStarGrid2D.xml +++ b/doc/classes/AStarGrid2D.xml @@ -182,9 +182,8 @@ The region of grid cells available for pathfinding. If changed, [method update] needs to be called before finding the next path. - + The size of the grid (number of cells of size [member cell_size] on each axis). If changed, [method update] needs to be called before finding the next path. - [i]Deprecated.[/i] Use [member region] instead. diff --git a/doc/classes/AnimatedTexture.xml b/doc/classes/AnimatedTexture.xml index a5cacff98784..aad16f6f3acd 100644 --- a/doc/classes/AnimatedTexture.xml +++ b/doc/classes/AnimatedTexture.xml @@ -1,5 +1,5 @@ - + Proxy texture for simple frame-based animations. @@ -9,7 +9,6 @@ [AnimatedTexture] currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one. [b]Note:[/b] AnimatedTexture doesn't support using [AtlasTexture]s. Each frame needs to be a separate [Texture2D]. [b]Warning:[/b] The current implementation is not efficient for the modern renderers. - [i]Deprecated.[/i] This class is deprecated, and might be removed in a future release. diff --git a/doc/classes/AnimationPlayer.xml b/doc/classes/AnimationPlayer.xml index 233d31a101dd..6236f96e63a9 100644 --- a/doc/classes/AnimationPlayer.xml +++ b/doc/classes/AnimationPlayer.xml @@ -44,10 +44,9 @@ Returns the blend time (in seconds) between two animations, referenced by their keys. - + - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeMethod]. @@ -57,10 +56,9 @@ Returns a negative value if the current animation is playing backwards. - + - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. @@ -69,10 +67,9 @@ Returns a list of the animation keys that are currently queued to play. - + - For backward compatibility. See [member AnimationMixer.root_node]. @@ -158,25 +155,22 @@ Specifies a blend time (in seconds) between two animations, referenced by their keys. - + - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeMethod]. - + - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. - + - For backward compatibility. See [member AnimationMixer.root_node]. @@ -235,20 +229,15 @@ - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]. + - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE]. + - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL]. + - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED]. + - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE]. + diff --git a/doc/classes/AnimationTree.xml b/doc/classes/AnimationTree.xml index 79e84192dfe4..3e0c088b8ae7 100644 --- a/doc/classes/AnimationTree.xml +++ b/doc/classes/AnimationTree.xml @@ -12,17 +12,15 @@ https://godotengine.org/asset-library/asset/678 - + - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. - + - For backward compatibility. See [enum AnimationMixer.AnimationCallbackModeProcess]. @@ -46,14 +44,11 @@ - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]. + - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE]. + - - For backward compatibility. See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL]. + diff --git a/doc/classes/CollisionShape3D.xml b/doc/classes/CollisionShape3D.xml index 4e32545f279d..0dcfa75e5be4 100644 --- a/doc/classes/CollisionShape3D.xml +++ b/doc/classes/CollisionShape3D.xml @@ -20,11 +20,11 @@ Sets the collision shape's shape to the addition of all its convexed [MeshInstance3D] siblings geometry. - + - [i]Obsoleted.[/i] Use [signal Resource.changed] instead. + This method does nothing. diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index a498bbeed38b..c3ec2b9e3cd2 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -1159,12 +1159,12 @@ [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. See also [constant NOTIFICATION_MOUSE_EXIT_SELF]. - + Sent when the mouse cursor enters the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. See also [constant NOTIFICATION_MOUSE_ENTER]. - + Sent when the mouse cursor leaves the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. See also [constant NOTIFICATION_MOUSE_EXIT]. diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 956157e8cbe0..08bdd840bb36 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -559,11 +559,10 @@ The callback should have 4 arguments: [Object] [code]undo_redo[/code], [Object] [code]modified_object[/code], [String] [code]property[/code] and [Variant] [code]new_value[/code]. They are, respectively, the [UndoRedo] object used by the inspector, the currently modified object, the name of the modified property and the new value the property is about to take. - + Returns the [EditorInterface] singleton instance. - [i]Deprecated.[/i] [EditorInterface] is a global singleton and can be accessed directly by its name. @@ -750,10 +749,9 @@ Emitted when user changes the workspace ([b]2D[/b], [b]3D[/b], [b]Script[/b], [b]AssetLib[/b]). Also works with custom screens defined by plugins. - + Emitted when any project setting has changed. - [i]Deprecated.[/i] Use [signal ProjectSettings.settings_changed] instead. diff --git a/doc/classes/EditorScript.xml b/doc/classes/EditorScript.xml index 8033c1891876..24480437fd97 100644 --- a/doc/classes/EditorScript.xml +++ b/doc/classes/EditorScript.xml @@ -48,11 +48,10 @@ [b]Warning:[/b] The implementation of this method is currently disabled. - + Returns the [EditorInterface] singleton instance. - [i]Deprecated.[/i] [EditorInterface] is a global singleton and can be accessed directly by its name. diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index 709d26668ca8..a9ac47d8dfaa 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -1,5 +1,5 @@ - + An editor for graph-like structures, using [GraphNode]s. diff --git a/doc/classes/GraphElement.xml b/doc/classes/GraphElement.xml index dd2c7f3d3e25..17c4184a20b2 100644 --- a/doc/classes/GraphElement.xml +++ b/doc/classes/GraphElement.xml @@ -1,5 +1,5 @@ - + A container that represents a basic element that can be placed inside a [GraphEdit] control. diff --git a/doc/classes/GraphNode.xml b/doc/classes/GraphNode.xml index 5bb3a25158eb..ad1028d7f430 100644 --- a/doc/classes/GraphNode.xml +++ b/doc/classes/GraphNode.xml @@ -1,5 +1,5 @@ - + A container with connection ports, representing a node in a [GraphEdit]. diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index f0385a781489..4befe2f8ec7d 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -322,11 +322,11 @@ HTTP status code [code]304 Not Modified[/code]. A conditional GET or HEAD request has been received and would have resulted in a 200 OK response if it were not for the fact that the condition evaluated to [code]false[/code]. - - [i]Deprecated.[/i] HTTP status code [code]305 Use Proxy[/code]. + + HTTP status code [code]305 Use Proxy[/code]. - - [i]Deprecated.[/i] HTTP status code [code]306 Switch Proxy[/code]. + + HTTP status code [code]306 Switch Proxy[/code]. HTTP status code [code]307 Temporary Redirect[/code]. The target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. diff --git a/doc/classes/InputEventJoypadButton.xml b/doc/classes/InputEventJoypadButton.xml index 2516ef67dd38..a545eaf811c4 100644 --- a/doc/classes/InputEventJoypadButton.xml +++ b/doc/classes/InputEventJoypadButton.xml @@ -16,9 +16,7 @@ If [code]true[/code], the button's state is pressed. If [code]false[/code], the button's state is released. - - Represents the pressure the user puts on a pressure-sensitive button. - [i]Deprecated.[/i] This property is never set by the engine and is always [code]0[/code]. + diff --git a/doc/classes/LightmapGIData.xml b/doc/classes/LightmapGIData.xml index db6c9e70ca43..b1ba6c5d848a 100644 --- a/doc/classes/LightmapGIData.xml +++ b/doc/classes/LightmapGIData.xml @@ -54,9 +54,8 @@ - + The lightmap atlas texture generated by the lightmapper. - [i]Deprecated.[/i] The lightmap atlas can now have multiple textures. See [member lightmap_textures]. The lightmap atlas textures generated by the lightmapper. diff --git a/doc/classes/MultiMesh.xml b/doc/classes/MultiMesh.xml index f83dadfb15d7..553921361903 100644 --- a/doc/classes/MultiMesh.xml +++ b/doc/classes/MultiMesh.xml @@ -90,11 +90,9 @@ - - See [method set_instance_color]. + - - See [method set_instance_custom_data]. + Number of instances that will get drawn. This clears and (re)sizes the buffers. Setting data format or flags afterwards will have no effect. @@ -104,11 +102,9 @@ [Mesh] resource to be instanced. The looks of the individual instances can be modified using [method set_instance_color] and [method set_instance_custom_data]. - - See [method set_instance_transform_2d]. + - - See [method set_instance_transform]. + Format of transform used to transform mesh, either 2D or 3D. diff --git a/doc/classes/NavigationAgent2D.xml b/doc/classes/NavigationAgent2D.xml index fc7faf9260d0..132ece53b042 100644 --- a/doc/classes/NavigationAgent2D.xml +++ b/doc/classes/NavigationAgent2D.xml @@ -1,5 +1,5 @@ - + A 2D agent used to pathfind to a position while avoiding obstacles. diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml index cbcf50bb2972..37f92ab42a27 100644 --- a/doc/classes/NavigationAgent3D.xml +++ b/doc/classes/NavigationAgent3D.xml @@ -1,5 +1,5 @@ - + A 3D agent used to pathfind to a position while avoiding obstacles. diff --git a/doc/classes/NavigationLink2D.xml b/doc/classes/NavigationLink2D.xml index 75b691aaf475..0892c9ec4404 100644 --- a/doc/classes/NavigationLink2D.xml +++ b/doc/classes/NavigationLink2D.xml @@ -1,5 +1,5 @@ - + A link between two positions on [NavigationRegion2D]s that agents can be routed through. diff --git a/doc/classes/NavigationLink3D.xml b/doc/classes/NavigationLink3D.xml index 711c637dc5be..0fcc106beb7f 100644 --- a/doc/classes/NavigationLink3D.xml +++ b/doc/classes/NavigationLink3D.xml @@ -1,5 +1,5 @@ - + A link between two positions on [NavigationRegion3D]s that agents can be routed through. diff --git a/doc/classes/NavigationMesh.xml b/doc/classes/NavigationMesh.xml index 8b2265baad52..42ef354bc894 100644 --- a/doc/classes/NavigationMesh.xml +++ b/doc/classes/NavigationMesh.xml @@ -1,5 +1,5 @@ - + A navigation mesh that defines traversable areas and obstacles. diff --git a/doc/classes/NavigationMeshGenerator.xml b/doc/classes/NavigationMeshGenerator.xml index 0997354aff05..35c9e13e58b6 100644 --- a/doc/classes/NavigationMeshGenerator.xml +++ b/doc/classes/NavigationMeshGenerator.xml @@ -1,5 +1,5 @@ - + Helper class for creating and clearing navigation meshes. @@ -14,7 +14,7 @@ $DOCS_URL/tutorials/navigation/navigation_using_navigationmeshes.html - + diff --git a/doc/classes/NavigationMeshSourceGeometryData2D.xml b/doc/classes/NavigationMeshSourceGeometryData2D.xml index 4bf5213da7fc..3f6fcc733a06 100644 --- a/doc/classes/NavigationMeshSourceGeometryData2D.xml +++ b/doc/classes/NavigationMeshSourceGeometryData2D.xml @@ -1,5 +1,5 @@ - + Container for parsed source geometry data used in navigation mesh baking. diff --git a/doc/classes/NavigationMeshSourceGeometryData3D.xml b/doc/classes/NavigationMeshSourceGeometryData3D.xml index dad36234169b..ffa8163eaaec 100644 --- a/doc/classes/NavigationMeshSourceGeometryData3D.xml +++ b/doc/classes/NavigationMeshSourceGeometryData3D.xml @@ -1,5 +1,5 @@ - + Container for parsed source geometry data used in navigation mesh baking. diff --git a/doc/classes/NavigationObstacle2D.xml b/doc/classes/NavigationObstacle2D.xml index 1eb18984a611..19b515c7cb2f 100644 --- a/doc/classes/NavigationObstacle2D.xml +++ b/doc/classes/NavigationObstacle2D.xml @@ -1,5 +1,5 @@ - + 2D Obstacle used in navigation to constrain avoidance controlled agents outside or inside an area. diff --git a/doc/classes/NavigationObstacle3D.xml b/doc/classes/NavigationObstacle3D.xml index 141442eaf007..998279b3c490 100644 --- a/doc/classes/NavigationObstacle3D.xml +++ b/doc/classes/NavigationObstacle3D.xml @@ -1,5 +1,5 @@ - + 3D Obstacle used in navigation to constrain avoidance controlled agents outside or inside an area. diff --git a/doc/classes/NavigationPathQueryParameters2D.xml b/doc/classes/NavigationPathQueryParameters2D.xml index 74cf4bdb7567..7d9ecf61b0b5 100644 --- a/doc/classes/NavigationPathQueryParameters2D.xml +++ b/doc/classes/NavigationPathQueryParameters2D.xml @@ -1,5 +1,5 @@ - + Provides parameters for 2D navigation path queries. diff --git a/doc/classes/NavigationPathQueryParameters3D.xml b/doc/classes/NavigationPathQueryParameters3D.xml index 2a366c0498a5..862f8a8347e2 100644 --- a/doc/classes/NavigationPathQueryParameters3D.xml +++ b/doc/classes/NavigationPathQueryParameters3D.xml @@ -1,5 +1,5 @@ - + Provides parameters for 3D navigation path queries. diff --git a/doc/classes/NavigationPathQueryResult2D.xml b/doc/classes/NavigationPathQueryResult2D.xml index e02133cfba07..e1ef2ee7de77 100644 --- a/doc/classes/NavigationPathQueryResult2D.xml +++ b/doc/classes/NavigationPathQueryResult2D.xml @@ -1,5 +1,5 @@ - + Represents the result of a 2D pathfinding query. diff --git a/doc/classes/NavigationPathQueryResult3D.xml b/doc/classes/NavigationPathQueryResult3D.xml index 9631c6a644f2..1cda3e64d593 100644 --- a/doc/classes/NavigationPathQueryResult3D.xml +++ b/doc/classes/NavigationPathQueryResult3D.xml @@ -1,5 +1,5 @@ - + Represents the result of a 3D pathfinding query. diff --git a/doc/classes/NavigationPolygon.xml b/doc/classes/NavigationPolygon.xml index 54c5c80b78c6..9c4e8169b054 100644 --- a/doc/classes/NavigationPolygon.xml +++ b/doc/classes/NavigationPolygon.xml @@ -1,5 +1,5 @@ - + A 2D navigation mesh that describes a traversable surface for pathfinding. @@ -132,11 +132,10 @@ Returns a [PackedVector2Array] containing all the vertices being used to create the polygons. - + Creates polygons from the outlines added in the editor or by script. - [i]Deprecated.[/i] This function is deprecated, and might be removed in a future release. Use [method NavigationServer2D.parse_source_geometry_data] and [method NavigationServer2D.bake_from_source_geometry_data] instead. diff --git a/doc/classes/NavigationRegion2D.xml b/doc/classes/NavigationRegion2D.xml index 4ad552e97ec7..8ce1551715b6 100644 --- a/doc/classes/NavigationRegion2D.xml +++ b/doc/classes/NavigationRegion2D.xml @@ -1,5 +1,5 @@ - + A traversable 2D region that [NavigationAgent2D]s can use for pathfinding. @@ -43,11 +43,10 @@ Returns the current navigation map [RID] used by this region. - + Returns the [RID] of this region on the [NavigationServer2D]. - [i]Deprecated.[/i] Use [method get_rid] instead. diff --git a/doc/classes/NavigationRegion3D.xml b/doc/classes/NavigationRegion3D.xml index 2a84270d7d8f..ad31fd06324b 100644 --- a/doc/classes/NavigationRegion3D.xml +++ b/doc/classes/NavigationRegion3D.xml @@ -1,5 +1,5 @@ - + A traversable 3D region that [NavigationAgent3D]s can use for pathfinding. @@ -36,11 +36,10 @@ Returns the current navigation map [RID] used by this region. - + Returns the [RID] of this region on the [NavigationServer3D]. - [i]Deprecated.[/i] Use [method get_rid] instead. diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index 2fe60a111885..39f0718a718b 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -1,5 +1,5 @@ - + A server interface for low-level 2D navigation access. diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index caadb844f174..95a803b6e561 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -1,5 +1,5 @@ - + A server interface for low-level 3D navigation access. @@ -886,13 +886,13 @@ Queries a path in a given navigation map. Start and target position and other parameters are defined through [NavigationPathQueryParameters3D]. Updates the provided [NavigationPathQueryResult3D] result object with the path among other results requested by the query. - + Bakes the [param navigation_mesh] with bake source geometry collected starting from the [param root_node]. - [i]Deprecated.[/i] This function is deprecated due to core threading changes. To upgrade existing code, first create a [NavigationMeshSourceGeometryData3D] resource. Use this resource with [method parse_source_geometry_data] to parse the SceneTree for nodes that should contribute to the navigation mesh baking. The SceneTree parsing needs to happen on the main thread. After the parsing is finished use the resource with [method bake_from_source_geometry_data] to bake a navigation mesh. + [i]Deprecated.[/i] To upgrade existing code, first create a [NavigationMeshSourceGeometryData3D] resource. Use this resource with [method parse_source_geometry_data] to parse the SceneTree for nodes that should contribute to the navigation mesh baking. The SceneTree parsing needs to happen on the main thread. After the parsing is finished use the resource with [method bake_from_source_geometry_data] to bake a navigation mesh. diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 02126bf8fef4..ada4bd04e6dc 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -1038,8 +1038,8 @@ Notification received when the node is about to exit a [SceneTree]. See [method _exit_tree]. This notification is received [i]after[/i] the related [signal tree_exiting] signal. - - [i]Deprecated.[/i] This notification is no longer emitted. Use [constant NOTIFICATION_CHILD_ORDER_CHANGED] instead. + + This notification is no longer emitted. Notification received when the node is ready. See [method _ready]. diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index 21b34db69df2..8969d66b35d8 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -14,12 +14,11 @@ $DOCS_URL/tutorials/shaders/compute_shaders.html - + - [i]Deprecated.[/i] Barriers are automatically inserted by RenderingDevice. @@ -190,12 +189,11 @@ Ends the command buffer debug label region started by a [method draw_command_begin_label] call. - + - [i]Deprecated.[/i] Inserting labels no longer applies due to command reordering. @@ -242,7 +240,7 @@ [b]Note:[/b] Cannot be used with local RenderingDevices, as these don't have a screen. If called on a local RenderingDevice, [method draw_list_begin_for_screen] returns [constant INVALID_ID]. - + @@ -256,7 +254,6 @@ - [i]Deprecated.[/i] Split draw lists are used automatically by RenderingDevice. @@ -347,11 +344,10 @@ Switches to the next draw pass. - + - [i]Deprecated.[/i] Split draw lists are used automatically by RenderingDevice. @@ -439,10 +435,9 @@ Tries to free an object in the RenderingDevice. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingDevice directly. - + - [i]Deprecated.[/i] Barriers are automatically inserted by RenderingDevice. @@ -804,13 +799,12 @@ Returns the data format used to create this texture. - + Returns the internal graphics handle for this texture object. For use when communicating with third-party APIs mostly with GDExtension. [b]Note:[/b] This function returns a [code]uint64_t[/code] which internally maps to a [code]GLuint[/code] (OpenGL) or [code]VkImage[/code] (Vulkan). - [i]Deprecated.[/i] Use [method get_driver_resource] with [constant DRIVER_RESOURCE_TEXTURE] instead. @@ -982,44 +976,31 @@ - Vulkan: [code]VkPipeline[/code]. - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_LOGICAL_DEVICE]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_PHYSICAL_DEVICE]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_TOPMOST_OBJECT]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_COMMAND_QUEUE]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_QUEUE_FAMILY]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_TEXTURE]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_TEXTURE_VIEW]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_TEXTURE_DATA_FORMAT]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_SAMPLER]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_UNIFORM_SET]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_BUFFER]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_COMPUTE_PIPELINE]. + - - [i]Deprecated.[/i] Use [constant DRIVER_RESOURCE_RENDER_PIPELINE]. + 4-bit-per-channel red/green channel data format, packed into 8 bits. Values are in the [code][0.0, 1.0][/code] range. @@ -2168,20 +2149,15 @@ Represents the size of the [enum InitialAction] enum. - - [i]Deprecated.[/i] Use [constant INITIAL_ACTION_CLEAR] instead. + - - [i]Deprecated.[/i] Use [constant INITIAL_ACTION_LOAD] instead. + - - [i]Deprecated.[/i] Use [constant INITIAL_ACTION_LOAD] instead. + - - [i]Deprecated.[/i] Use [constant INITIAL_ACTION_DISCARD] instead. + - - [i]Deprecated.[/i] Use [constant INITIAL_ACTION_LOAD] instead. + Store the result of the draw list in the framebuffer. This is generally what you want to do. @@ -2192,11 +2168,9 @@ Represents the size of the [enum FinalAction] enum. - - [i]Deprecated.[/i] Use [constant FINAL_ACTION_STORE] instead. + - - [i]Deprecated.[/i] Use [constant FINAL_ACTION_STORE] instead. + Vertex shader stage. This can be used to manipulate vertices from a shader (but not create new vertices). diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 4ab511b5a908..4597e50f37be 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -1556,11 +1556,11 @@ Returns [code]true[/code] if changes have been made to the RenderingServer's data. [method force_draw] is usually called if this happens. - + - [i]Deprecated.[/i] This method has not been used since Godot 3.0. Always returns false. + Always returns false. @@ -3371,19 +3371,19 @@ Returns a texture [RID] that can be used with [RenderingDevice]. - + - [i]Deprecated.[/i] ProxyTexture was removed in Godot 4, so this method does nothing when called and always returns a null [RID]. + This method does nothing when called and always returns a null [RID]. - + - [i]Deprecated.[/i] ProxyTexture was removed in Godot 4, so this method cannot be used anymore. + This method should not be used. @@ -4044,8 +4044,8 @@ The maximum number of glow levels that can be used with the glow post-processing effect. - - [i]Deprecated.[/i] This constant is unused internally. + + This constant is unused internally. The maximum number of directional lights that can be rendered at a given time in 2D. @@ -5340,11 +5340,9 @@ Video memory used (in bytes). When using the Forward+ or mobile rendering backends, this is always greater than the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED], since there is miscellaneous data not accounted for by those two metrics. When using the GL Compatibility backend, this is equal to the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED]. - - [i]Deprecated.[/i] This constant has not been used since Godot 3.0. + - - [i]Deprecated.[/i] This constant has not been used since Godot 3.0. + diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 49db3f81b448..ee6546dd1480 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -71,11 +71,10 @@ Returns the [RID] of this resource (or an empty RID). Many resources (such as [Texture2D], [Mesh], and so on) are high-level abstractions of resources stored in a specialized server ([DisplayServer], [RenderingServer], etc.), so this function will return the original [RID]. - + Calls [method _setup_local_to_scene]. If [member resource_local_to_scene] is set to [code]true[/code], this method is automatically called from [method PackedScene.instantiate] by the newly duplicated resource within the scene instance. - [i]Deprecated.[/i] This method should only be called internally. Override [method _setup_local_to_scene] instead. @@ -107,10 +106,9 @@ [b]Note:[/b] This signal is not emitted automatically for properties of custom resources. If necessary, a setter needs to be created to emit the signal. - + - Emitted by a newly duplicated resource with [member resource_local_to_scene] set to [code]true[/code]. - [i]Deprecated.[/i] This signal is only emitted when the resource is created. Override [method _setup_local_to_scene] instead. + Emitted by a newly duplicated resource with [member resource_local_to_scene] set to [code]true[/code]. diff --git a/doc/classes/ScriptLanguageExtension.xml b/doc/classes/ScriptLanguageExtension.xml index c5248f48889b..e2ad1ca3e4df 100644 --- a/doc/classes/ScriptLanguageExtension.xml +++ b/doc/classes/ScriptLanguageExtension.xml @@ -203,10 +203,9 @@ - + - [i]Deprecated.[/i] This method is not called by the engine. diff --git a/doc/classes/ShapeCast3D.xml b/doc/classes/ShapeCast3D.xml index e189628f4c57..ff057e8c7070 100644 --- a/doc/classes/ShapeCast3D.xml +++ b/doc/classes/ShapeCast3D.xml @@ -119,11 +119,11 @@ Removes a collision exception so the shape does report collisions with the specified [RID]. - + - [i]Obsoleted.[/i] Use [signal Resource.changed] instead. + This method does nothing. diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index 2a629abc0db3..360fc9b2a9c2 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -44,11 +44,10 @@ Returns the bone index that matches [param name] as its name. - + Force updates the bone transforms/poses for all bones in the skeleton. - [i]Deprecated.[/i] Do not use. diff --git a/doc/classes/SkeletonIK3D.xml b/doc/classes/SkeletonIK3D.xml index c72383c84feb..d1f96adec246 100644 --- a/doc/classes/SkeletonIK3D.xml +++ b/doc/classes/SkeletonIK3D.xml @@ -1,5 +1,5 @@ - + A node used to rotate all bones of a [Skeleton3D] bone chain a way that places the end bone at a desired 3D position. @@ -24,7 +24,6 @@ # Apply zero IK effect (a value at or below 0.01 also removes bones_global_pose_override on Skeleton) skeleton_ik_node.set_interpolation(0.0) [/codeblock] - [i]Deprecated.[/i] This class is deprecated, and might be removed in a future release. https://godotengine.org/asset-library/asset/523 diff --git a/doc/classes/SkeletonModification2D.xml b/doc/classes/SkeletonModification2D.xml index c1eee9cb5c31..c09e63be85f3 100644 --- a/doc/classes/SkeletonModification2D.xml +++ b/doc/classes/SkeletonModification2D.xml @@ -1,5 +1,5 @@ - + Base class for resources that operate on [Bone2D]s in a [Skeleton2D]. diff --git a/doc/classes/SkeletonModification2DCCDIK.xml b/doc/classes/SkeletonModification2DCCDIK.xml index af71ae809c10..e20cbd896056 100644 --- a/doc/classes/SkeletonModification2DCCDIK.xml +++ b/doc/classes/SkeletonModification2DCCDIK.xml @@ -1,5 +1,5 @@ - + A modification that uses CCDIK to manipulate a series of bones to reach a target in 2D. diff --git a/doc/classes/SkeletonModification2DFABRIK.xml b/doc/classes/SkeletonModification2DFABRIK.xml index a31c908082c7..16784dbf4d88 100644 --- a/doc/classes/SkeletonModification2DFABRIK.xml +++ b/doc/classes/SkeletonModification2DFABRIK.xml @@ -1,5 +1,5 @@ - + A modification that uses FABRIK to manipulate a series of [Bone2D] nodes to reach a target. diff --git a/doc/classes/SkeletonModification2DJiggle.xml b/doc/classes/SkeletonModification2DJiggle.xml index 7683d29d1c88..4a09806b82ef 100644 --- a/doc/classes/SkeletonModification2DJiggle.xml +++ b/doc/classes/SkeletonModification2DJiggle.xml @@ -1,5 +1,5 @@ - + A modification that jiggles [Bone2D] nodes as they move towards a target. diff --git a/doc/classes/SkeletonModification2DLookAt.xml b/doc/classes/SkeletonModification2DLookAt.xml index 797722eb8634..232104f6acf6 100644 --- a/doc/classes/SkeletonModification2DLookAt.xml +++ b/doc/classes/SkeletonModification2DLookAt.xml @@ -1,5 +1,5 @@ - + A modification that rotates a [Bone2D] node to look at a target. diff --git a/doc/classes/SkeletonModification2DPhysicalBones.xml b/doc/classes/SkeletonModification2DPhysicalBones.xml index 930f201ad5fe..163fab892c33 100644 --- a/doc/classes/SkeletonModification2DPhysicalBones.xml +++ b/doc/classes/SkeletonModification2DPhysicalBones.xml @@ -1,5 +1,5 @@ - + A modification that applies the transforms of [PhysicalBone2D] nodes to [Bone2D] nodes. diff --git a/doc/classes/SkeletonModification2DStackHolder.xml b/doc/classes/SkeletonModification2DStackHolder.xml index 60fba86d3273..5b9f6f270ace 100644 --- a/doc/classes/SkeletonModification2DStackHolder.xml +++ b/doc/classes/SkeletonModification2DStackHolder.xml @@ -1,5 +1,5 @@ - + A modification that holds and executes a [SkeletonModificationStack2D]. diff --git a/doc/classes/SkeletonModification2DTwoBoneIK.xml b/doc/classes/SkeletonModification2DTwoBoneIK.xml index 2206aa57190e..1c7bb32f4a40 100644 --- a/doc/classes/SkeletonModification2DTwoBoneIK.xml +++ b/doc/classes/SkeletonModification2DTwoBoneIK.xml @@ -1,5 +1,5 @@ - + A modification that rotates two bones using the law of cosines to reach the target. diff --git a/doc/classes/SkeletonModificationStack2D.xml b/doc/classes/SkeletonModificationStack2D.xml index 391771d1d34e..a006f727eed7 100644 --- a/doc/classes/SkeletonModificationStack2D.xml +++ b/doc/classes/SkeletonModificationStack2D.xml @@ -1,5 +1,5 @@ - + A resource that holds a stack of [SkeletonModification2D]s. diff --git a/doc/classes/StreamPeerGZIP.xml b/doc/classes/StreamPeerGZIP.xml index fc22f72df912..e3f8441d195e 100644 --- a/doc/classes/StreamPeerGZIP.xml +++ b/doc/classes/StreamPeerGZIP.xml @@ -1,5 +1,5 @@ - + A stream peer that handles GZIP and deflate compression/decompression. diff --git a/doc/classes/SubViewportContainer.xml b/doc/classes/SubViewportContainer.xml index e47e27c0ce76..b7d097cc9192 100644 --- a/doc/classes/SubViewportContainer.xml +++ b/doc/classes/SubViewportContainer.xml @@ -11,7 +11,7 @@ - + diff --git a/doc/classes/SurfaceTool.xml b/doc/classes/SurfaceTool.xml index 32c5f8dff745..6df5a4d18e47 100644 --- a/doc/classes/SurfaceTool.xml +++ b/doc/classes/SurfaceTool.xml @@ -119,13 +119,12 @@ Removes the index array by expanding the vertex array. - + Generates a LOD for a given [param nd_threshold] in linear units (square root of quadric error metric), using at most [param target_index_count] indices. - [i]Deprecated.[/i] Unused internally and fails to preserve normals or UVs. Consider using [method ImporterMesh.generate_lods] instead. diff --git a/doc/classes/TextureRect.xml b/doc/classes/TextureRect.xml index d5f60839b932..73fbbb783e58 100644 --- a/doc/classes/TextureRect.xml +++ b/doc/classes/TextureRect.xml @@ -10,7 +10,7 @@ https://godotengine.org/asset-library/asset/676 - + Defines how minimum size is determined based on the texture's size. See [enum ExpandMode] for options. [b]Note:[/b] Using [constant EXPAND_FIT_WIDTH], [constant EXPAND_FIT_WIDTH_PROPORTIONAL], [constant EXPAND_FIT_HEIGHT] or [constant EXPAND_FIT_HEIGHT_PROPORTIONAL] may result in unstable behavior in some containers. This functionality is being re-evaluated and will change in the future. diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index 695ffca1a3f2..e1e16e86a764 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -76,11 +76,10 @@ Clears cells that do not exist in the tileset. - + - [i]Deprecated.[/i] See [method notify_runtime_tile_data_update] and [method update_internals]. @@ -196,7 +195,7 @@ Returns the number of layers in the TileMap. - + @@ -445,7 +444,7 @@ If [param layer] is negative, the layers are accessed from the last one. - + diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml index 66a42d4bb4fe..b79a8cbdb49e 100644 --- a/doc/classes/TreeItem.xml +++ b/doc/classes/TreeItem.xml @@ -568,7 +568,7 @@ Sets the given column's custom color. - + @@ -576,7 +576,6 @@ Sets the given column's custom draw callback to [param callback] method on [param object]. The [param callback] should accept two arguments: the [TreeItem] that is drawn and its position and size as a [Rect2]. - [i]Deprecated.[/i] Use [method TreeItem.set_custom_draw_callback] instead. diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 6d8ada9370d3..711f6eadf838 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -187,7 +187,7 @@ Helper method which calls the [code]set_text()[/code] method on the currently focused [Control], provided that it is defined (e.g. if the focused Control is [Button] or [LineEdit]). - + @@ -202,7 +202,6 @@ If an earlier method marks the input as handled via [method set_input_as_handled], any later method in this list will not be called. If none of the methods handle the event and [member physics_object_picking] is [code]true[/code], the event is used for physics object picking. [b]Note:[/b] This method doesn't propagate input events to embedded [Window]s or [SubViewport]s. - [i]Deprecated.[/i] Use [method push_input] instead. diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index ab14f64aa1c4..57d26bf38442 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -357,11 +357,10 @@ Centers a native window on the current screen and an embedded window on its embedder [Viewport]. - + Moves the [Window] on top of other windows and focuses it. - [i]Deprecated.[/i] Use [method Window.grab_focus] instead. diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml index 6fb43d77d97f..5276e0537907 100644 --- a/doc/classes/XRInterface.xml +++ b/doc/classes/XRInterface.xml @@ -102,18 +102,16 @@ Is [code]true[/code] if this interface has been initialized. - + Is [code]true[/code] if passthrough is enabled. - [i]Deprecated.[/i] Check if [member environment_blend_mode] is [constant XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND], instead. - + Is [code]true[/code] if this interface supports passthrough. - [i]Deprecated.[/i] Check that [constant XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND] is supported using [method get_supported_environment_blend_modes], instead. @@ -146,19 +144,17 @@ [b]Note:[/b] Changing this after the interface has already been initialized can be jarring for the player, so it's recommended to recenter on the HMD with [method XRServer.center_on_hmd] (if switching to [constant XRInterface.XR_PLAY_AREA_STAGE]) or make the switch during a scene change. - + Starts passthrough, will return [code]false[/code] if passthrough couldn't be started. [b]Note:[/b] The viewport used for XR must have a transparent background, otherwise passthrough may not properly render. - [i]Deprecated.[/i] Set the [member environment_blend_mode] to [constant XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND], instead. - + Stops passthrough. - [i]Deprecated.[/i] Set the [member environment_blend_mode] to [constant XRInterface.XR_ENV_BLEND_MODE_OPAQUE], instead. diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 76a665d3c05c..e52d863f7d4a 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -77,6 +77,15 @@ "There is currently no description for this operator. Please help us by :ref:`contributing one `!", "There is currently no description for this theme property. Please help us by :ref:`contributing one `!", "There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information.", + "Deprecated:", + "Experimental:", + "This signal may be changed or removed in future versions.", + "This constant may be changed or removed in future versions.", + "This property may be changed or removed in future versions.", + "This constructor may be changed or removed in future versions.", + "This method may be changed or removed in future versions.", + "This operator may be changed or removed in future versions.", + "This theme property may be changed or removed in future versions.", ] strings_l10n: Dict[str, str] = {} @@ -158,6 +167,9 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: if inherits is not None: class_def.inherits = inherits + class_def.deprecated = class_root.get("deprecated") + class_def.experimental = class_root.get("experimental") + brief_desc = class_root.find("brief_description") if brief_desc is not None and brief_desc.text: class_def.brief_description = brief_desc.text @@ -191,6 +203,8 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: property_def = PropertyDef( property_name, type_name, setter, getter, property.text, default_value, overrides ) + property_def.deprecated = property.get("deprecated") + property_def.experimental = property.get("experimental") class_def.properties[property_name] = property_def constructors = class_root.find("constructors") @@ -216,6 +230,8 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers) method_def.definition_name = "constructor" + method_def.deprecated = constructor.get("deprecated") + method_def.experimental = constructor.get("experimental") if method_name not in class_def.constructors: class_def.constructors[method_name] = [] @@ -244,6 +260,8 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: method_desc = desc_element.text method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers) + method_def.deprecated = method.get("deprecated") + method_def.experimental = method.get("experimental") if method_name not in class_def.methods: class_def.methods[method_name] = [] @@ -273,6 +291,8 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers) method_def.definition_name = "operator" + method_def.deprecated = operator.get("deprecated") + method_def.experimental = operator.get("experimental") if method_name not in class_def.operators: class_def.operators[method_name] = [] @@ -288,6 +308,8 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: enum = constant.get("enum") is_bitfield = constant.get("is_bitfield") == "true" constant_def = ConstantDef(constant_name, value, constant.text, is_bitfield) + constant_def.deprecated = constant.get("deprecated") + constant_def.experimental = constant.get("experimental") if enum is None: if constant_name in class_def.constants: print_error(f'{class_name}.xml: Duplicate constant "{constant_name}".', self) @@ -345,6 +367,8 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: signal_desc = desc_element.text signal_def = SignalDef(signal_name, params, signal_desc) + signal_def.deprecated = signal.get("deprecated") + signal_def.experimental = signal.get("experimental") class_def.signals[signal_name] = signal_def theme_items = class_root.find("theme_items") @@ -357,7 +381,7 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None: theme_item_id = "{}_{}".format(theme_item_data_name, theme_item_name) if theme_item_id in class_def.theme_items: print_error( - f'{class_name}.xml: Duplicate theme item "{theme_item_name}" of type "{theme_item_data_name}".', + f'{class_name}.xml: Duplicate theme property "{theme_item_name}" of type "{theme_item_data_name}".', self, ) continue @@ -447,6 +471,8 @@ def __init__( ) -> None: self.definition_name = definition_name self.name = name + self.deprecated: Optional[str] = None + self.experimental: Optional[str] = None class PropertyDef(DefinitionBase): @@ -540,7 +566,7 @@ class ThemeItemDef(DefinitionBase): def __init__( self, name: str, type_name: TypeName, data_name: str, text: Optional[str], default_value: Optional[str] ) -> None: - super().__init__("theme item", name) + super().__init__("theme property", name) self.type_name = type_name self.data_name = data_name @@ -892,6 +918,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(f".. _class_{class_name}:\n\n") f.write(make_heading(class_name, "=", False)) + f.write(make_deprecated_experimental(class_def, state)) + ### INHERITANCE TREE ### # Ascendants @@ -1066,6 +1094,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add signal description, or a call to action if it's missing. + f.write(make_deprecated_experimental(signal, state)) + if signal.description is not None and signal.description.strip() != "": f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") else: @@ -1111,6 +1141,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add enum constant description. + f.write(make_deprecated_experimental(value, state)) + if value.text is not None and value.text.strip() != "": f.write(f"{format_text_block(value.text.strip(), value, state)}") else: @@ -1140,7 +1172,9 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(f"**{constant.name}** = ``{constant.value}``\n\n") - # Add enum constant description. + # Add constant description. + + f.write(make_deprecated_experimental(constant, state)) if constant.text is not None and constant.text.strip() != "": f.write(f"{format_text_block(constant.text.strip(), constant, state)}") @@ -1236,6 +1270,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add property description, or a call to action if it's missing. + f.write(make_deprecated_experimental(property_def, state)) + if property_def.text is not None and property_def.text.strip() != "": f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n") else: @@ -1274,6 +1310,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add constructor description, or a call to action if it's missing. + f.write(make_deprecated_experimental(m, state)) + if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") else: @@ -1315,6 +1353,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add method description, or a call to action if it's missing. + f.write(make_deprecated_experimental(m, state)) + if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") else: @@ -1355,6 +1395,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add operator description, or a call to action if it's missing. + f.write(make_deprecated_experimental(m, state)) + if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") else: @@ -1392,6 +1434,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Add theme property description, or a call to action if it's missing. + f.write(make_deprecated_experimental(theme_item_def, state)) + if theme_item_def.text is not None and theme_item_def.text.strip() != "": f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n") else: @@ -1542,6 +1586,28 @@ def make_getter_signature(class_def: ClassDef, property_def: PropertyDef, state: return f"{ret_type} {signature}" +def make_deprecated_experimental(item: DefinitionBase, state: State) -> str: + result = "" + + if item.deprecated is not None: + deprecated_prefix = translate("Deprecated:") + if item.deprecated.strip() == "": + default_message = translate(f"This {item.definition_name} may be changed or removed in future versions.") + result += f"**{deprecated_prefix}** {default_message}\n\n" + else: + result += f"**{deprecated_prefix}** {format_text_block(item.deprecated.strip(), item, state)}\n\n" + + if item.experimental is not None: + experimental_prefix = translate("Experimental:") + if item.experimental.strip() == "": + default_message = translate(f"This {item.definition_name} may be changed or removed in future versions.") + result += f"**{experimental_prefix}** {default_message}\n\n" + else: + result += f"**{experimental_prefix}** {format_text_block(item.experimental.strip(), item, state)}\n\n" + + return result + + def make_heading(title: str, underline: str, l10n: bool = True) -> str: if l10n: new_title = translate(title) @@ -1965,7 +2031,7 @@ def format_text_block( elif target_name in class_def.theme_items: print_warning( - f'{state.current_class}.xml: Found a code string "{inside_code_text}" that matches the {target_class_name}.{target_name} theme item in {context_name}. {code_warning_if_intended_string}', + f'{state.current_class}.xml: Found a code string "{inside_code_text}" that matches the {target_class_name}.{target_name} theme property in {context_name}. {code_warning_if_intended_string}', state, ) @@ -2076,7 +2142,7 @@ def format_text_block( elif tag_state.name == "theme_item": if target_name not in class_def.theme_items: print_error( - f'{state.current_class}.xml: Unresolved theme item reference "{link_target}" in {context_name}.', + f'{state.current_class}.xml: Unresolved theme property reference "{link_target}" in {context_name}.', state, ) else: diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp index 18c6c8b69b9f..ee3e54e9df89 100644 --- a/editor/doc_tools.cpp +++ b/editor/doc_tools.cpp @@ -87,7 +87,9 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::ClassDoc &cf = p_data.class_list[c.name]; c.is_deprecated = cf.is_deprecated; + c.deprecated_message = cf.deprecated_message; c.is_experimental = cf.is_experimental; + c.experimental_message = cf.experimental_message; c.keywords = cf.keywords; c.description = cf.description; @@ -139,7 +141,9 @@ void DocTools::merge_from(const DocTools &p_data) { m.description = mf.description; m.is_deprecated = mf.is_deprecated; + m.deprecated_message = mf.deprecated_message; m.is_experimental = mf.is_experimental; + m.experimental_message = mf.experimental_message; break; } } @@ -156,7 +160,9 @@ void DocTools::merge_from(const DocTools &p_data) { m.description = mf.description; m.is_deprecated = mf.is_deprecated; + m.deprecated_message = mf.deprecated_message; m.is_experimental = mf.is_experimental; + m.experimental_message = mf.experimental_message; m.keywords = mf.keywords; break; } @@ -173,7 +179,9 @@ void DocTools::merge_from(const DocTools &p_data) { m.description = mf.description; m.is_deprecated = mf.is_deprecated; + m.deprecated_message = mf.deprecated_message; m.is_experimental = mf.is_experimental; + m.experimental_message = mf.experimental_message; m.keywords = mf.keywords; break; } @@ -190,7 +198,9 @@ void DocTools::merge_from(const DocTools &p_data) { m.description = mf.description; m.is_deprecated = mf.is_deprecated; + m.deprecated_message = mf.deprecated_message; m.is_experimental = mf.is_experimental; + m.experimental_message = mf.experimental_message; m.keywords = mf.keywords; break; } @@ -207,7 +217,9 @@ void DocTools::merge_from(const DocTools &p_data) { m.description = mf.description; m.is_deprecated = mf.is_deprecated; + m.deprecated_message = mf.deprecated_message; m.is_experimental = mf.is_experimental; + m.experimental_message = mf.experimental_message; m.keywords = mf.keywords; break; } @@ -224,7 +236,9 @@ void DocTools::merge_from(const DocTools &p_data) { p.description = pf.description; p.is_deprecated = pf.is_deprecated; + p.deprecated_message = pf.deprecated_message; p.is_experimental = pf.is_experimental; + p.experimental_message = pf.experimental_message; p.keywords = pf.keywords; break; } @@ -290,7 +304,9 @@ void DocTools::merge_from(const DocTools &p_data) { m.description = mf.description; m.is_deprecated = mf.is_deprecated; + m.deprecated_message = mf.deprecated_message; m.is_experimental = mf.is_experimental; + m.experimental_message = mf.experimental_message; break; } } @@ -1068,12 +1084,22 @@ static Error _parse_methods(Ref &parser, Vector & if (parser->has_attribute("qualifiers")) { method.qualifiers = parser->get_named_attribute_value("qualifiers"); } +#ifndef DISABLE_DEPRECATED if (parser->has_attribute("is_deprecated")) { method.is_deprecated = parser->get_named_attribute_value("is_deprecated").to_lower() == "true"; } if (parser->has_attribute("is_experimental")) { method.is_experimental = parser->get_named_attribute_value("is_experimental").to_lower() == "true"; } +#endif + if (parser->has_attribute("deprecated")) { + method.is_deprecated = true; + method.deprecated_message = parser->get_named_attribute_value("deprecated"); + } + if (parser->has_attribute("experimental")) { + method.is_experimental = true; + method.experimental_message = parser->get_named_attribute_value("experimental"); + } if (parser->has_attribute("keywords")) { method.keywords = parser->get_named_attribute_value("keywords"); } @@ -1216,13 +1242,22 @@ Error DocTools::_load(Ref parser) { inheriting[c.inherits].insert(name); +#ifndef DISABLE_DEPRECATED if (parser->has_attribute("is_deprecated")) { c.is_deprecated = parser->get_named_attribute_value("is_deprecated").to_lower() == "true"; } - if (parser->has_attribute("is_experimental")) { c.is_experimental = parser->get_named_attribute_value("is_experimental").to_lower() == "true"; } +#endif + if (parser->has_attribute("deprecated")) { + c.is_deprecated = true; + c.deprecated_message = parser->get_named_attribute_value("deprecated"); + } + if (parser->has_attribute("experimental")) { + c.is_experimental = true; + c.experimental_message = parser->get_named_attribute_value("experimental"); + } if (parser->has_attribute("keywords")) { c.keywords = parser->get_named_attribute_value("keywords"); @@ -1304,12 +1339,22 @@ Error DocTools::_load(Ref parser) { prop2.is_bitfield = parser->get_named_attribute_value("is_bitfield").to_lower() == "true"; } } +#ifndef DISABLE_DEPRECATED if (parser->has_attribute("is_deprecated")) { prop2.is_deprecated = parser->get_named_attribute_value("is_deprecated").to_lower() == "true"; } if (parser->has_attribute("is_experimental")) { prop2.is_experimental = parser->get_named_attribute_value("is_experimental").to_lower() == "true"; } +#endif + if (parser->has_attribute("deprecated")) { + prop2.is_deprecated = true; + prop2.deprecated_message = parser->get_named_attribute_value("deprecated"); + } + if (parser->has_attribute("experimental")) { + prop2.is_experimental = true; + prop2.experimental_message = parser->get_named_attribute_value("experimental"); + } if (parser->has_attribute("keywords")) { prop2.keywords = parser->get_named_attribute_value("keywords"); } @@ -1380,12 +1425,22 @@ Error DocTools::_load(Ref parser) { constant2.is_bitfield = parser->get_named_attribute_value("is_bitfield").to_lower() == "true"; } } +#ifndef DISABLE_DEPRECATED if (parser->has_attribute("is_deprecated")) { constant2.is_deprecated = parser->get_named_attribute_value("is_deprecated").to_lower() == "true"; } if (parser->has_attribute("is_experimental")) { constant2.is_experimental = parser->get_named_attribute_value("is_experimental").to_lower() == "true"; } +#endif + if (parser->has_attribute("deprecated")) { + constant2.is_deprecated = true; + constant2.deprecated_message = parser->get_named_attribute_value("deprecated"); + } + if (parser->has_attribute("experimental")) { + constant2.is_experimental = true; + constant2.experimental_message = parser->get_named_attribute_value("experimental"); + } if (parser->has_attribute("keywords")) { constant2.keywords = parser->get_named_attribute_value("keywords"); } @@ -1438,21 +1493,21 @@ static void _write_method_doc(Ref f, const String &p_name, Vector"); + _write_string(f, 2, "<" + p_name + " name=\"" + m.name.xml_escape(true) + "\"" + additional_attributes + ">"); if (!m.return_type.is_empty()) { String enum_text; if (!m.return_enum.is_empty()) { - enum_text = " enum=\"" + m.return_enum + "\""; + enum_text = " enum=\"" + m.return_enum.xml_escape(true) + "\""; if (m.return_is_bitfield) { enum_text += " is_bitfield=\"true\""; } @@ -1470,16 +1525,16 @@ static void _write_method_doc(Ref f, const String &p_name, Vector"); + _write_string(f, 3, ""); } else { - _write_string(f, 3, ""); + _write_string(f, 3, ""); } } @@ -1517,10 +1572,10 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap"); for (int i = 0; i < c.tutorials.size(); i++) { DocData::TutorialDoc tutorial = c.tutorials.get(i); - String title_attribute = (!tutorial.title.is_empty()) ? " title=\"" + _translate_doc_string(tutorial.title).xml_escape() + "\"" : ""; + String title_attribute = (!tutorial.title.is_empty()) ? " title=\"" + _translate_doc_string(tutorial.title).xml_escape(true) + "\"" : ""; _write_string(f, 2, "" + tutorial.link.xml_escape() + ""); } _write_string(f, 1, ""); @@ -1565,7 +1620,7 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap"); + _write_string(f, 2, ""); } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); _write_string(f, 3, _translate_doc_string(p.description).strip_edges().xml_escape()); _write_string(f, 2, ""); } @@ -1605,10 +1660,10 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap"); + _write_string(f, 2, ""); } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } } else { if (!k.enumeration.is_empty()) { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } } _write_string(f, 3, _translate_doc_string(k.description).strip_edges().xml_escape()); @@ -1655,7 +1710,7 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap"); + _write_string(f, 2, ""); _write_string(f, 3, _translate_doc_string(ti.description).strip_edges().xml_escape()); diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp index 7f15eca11dc4..a31da1bd1363 100644 --- a/editor/editor_help.cpp +++ b/editor/editor_help.cpp @@ -211,7 +211,7 @@ void EditorHelp::_class_desc_select(const String &p_select) { emit_signal(SNAME("go_to_help"), "class_name:" + p_select.substr(1, p_select.length())); return; } else if (p_select.begins_with("@")) { - int tag_end = p_select.find(" "); + int tag_end = p_select.find_char(' '); String tag = p_select.substr(1, tag_end - 1); String link = p_select.substr(tag_end + 1, p_select.length()).lstrip(" "); @@ -244,7 +244,7 @@ void EditorHelp::_class_desc_select(const String &p_select) { topic = "class_annotation"; table = &annotation_line; } else if (tag == "theme_item") { - topic = "theme_item"; + topic = "class_theme_item"; table = &theme_property_line; } else { return; @@ -284,7 +284,7 @@ void EditorHelp::_class_desc_select(const String &p_select) { } if (link.contains(".")) { - int class_end = link.find("."); + int class_end = link.find_char('.'); emit_signal(SNAME("go_to_help"), topic + ":" + link.substr(0, class_end) + ":" + link.substr(class_end + 1, link.length())); } } @@ -317,8 +317,8 @@ void EditorHelp::_add_type(const String &p_type, const String &p_enum, bool p_is class_desc->push_color(Color(theme_cache.type_color, 0.5)); class_desc->push_hint(TTR("No return value.")); class_desc->add_text("void"); - class_desc->pop(); - class_desc->pop(); + class_desc->pop(); // hint + class_desc->pop(); // color return; } @@ -345,15 +345,15 @@ void EditorHelp::_add_type(const String &p_type, const String &p_enum, bool p_is class_desc->push_meta("#Array"); // class class_desc->add_text("Array"); - class_desc->pop(); + class_desc->pop(); // meta class_desc->add_text("["); } else if (is_bitfield) { class_desc->push_color(Color(theme_cache.type_color, 0.5)); class_desc->push_hint(TTR("This value is an integer composed as a bitmask of the following flags.")); class_desc->add_text("BitField"); - class_desc->pop(); + class_desc->pop(); // hint class_desc->add_text("["); - class_desc->pop(); + class_desc->pop(); // color } if (is_enum_type) { @@ -370,10 +370,10 @@ void EditorHelp::_add_type(const String &p_type, const String &p_enum, bool p_is } else if (is_bitfield) { class_desc->push_color(Color(theme_cache.type_color, 0.5)); class_desc->add_text("]"); - class_desc->pop(); + class_desc->pop(); // color } } - class_desc->pop(); + class_desc->pop(); // color } void EditorHelp::_add_type_icon(const String &p_type, int p_size, const String &p_fallback) { @@ -405,23 +405,60 @@ String EditorHelp::_fix_constant(const String &p_constant) const { return p_constant; } -// Macros for assigning the deprecation/experimental information to class members +// Macros for assigning the deprecated/experimental marks to class members in overview. + #define DEPRECATED_DOC_TAG \ + class_desc->push_font(theme_cache.doc_bold_font); \ class_desc->push_color(get_theme_color(SNAME("error_color"), EditorStringName(Editor))); \ Ref error_icon = get_editor_theme_icon(SNAME("StatusError")); \ - class_desc->add_text(" "); \ class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); \ - class_desc->add_text(" (" + TTR("Deprecated") + ")"); \ + class_desc->add_text(String::chr(160) + TTR("Deprecated")); \ + class_desc->pop(); \ class_desc->pop(); #define EXPERIMENTAL_DOC_TAG \ + class_desc->push_font(theme_cache.doc_bold_font); \ class_desc->push_color(get_theme_color(SNAME("warning_color"), EditorStringName(Editor))); \ Ref warning_icon = get_editor_theme_icon(SNAME("NodeWarning")); \ - class_desc->add_text(" "); \ class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); \ - class_desc->add_text(" (" + TTR("Experimental") + ")"); \ + class_desc->add_text(String::chr(160) + TTR("Experimental")); \ + class_desc->pop(); \ class_desc->pop(); +// Macros for displaying the deprecated/experimental info in class member descriptions. + +#define DEPRECATED_DOC_MSG(m_message, m_default_message) \ + Ref error_icon = get_editor_theme_icon(SNAME("StatusError")); \ + class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); \ + class_desc->add_text(" "); \ + class_desc->push_color(get_theme_color(SNAME("error_color"), EditorStringName(Editor))); \ + class_desc->push_font(theme_cache.doc_bold_font); \ + class_desc->add_text(TTR("Deprecated:")); \ + class_desc->pop(); \ + class_desc->pop(); \ + class_desc->add_text(" "); \ + if ((m_message).is_empty()) { \ + class_desc->add_text(m_default_message); \ + } else { \ + _add_text(m_message); \ + } + +#define EXPERIMENTAL_DOC_MSG(m_message, m_default_message) \ + Ref warning_icon = get_editor_theme_icon(SNAME("NodeWarning")); \ + class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); \ + class_desc->add_text(" "); \ + class_desc->push_color(get_theme_color(SNAME("warning_color"), EditorStringName(Editor))); \ + class_desc->push_font(theme_cache.doc_bold_font); \ + class_desc->add_text(TTR("Experimental:")); \ + class_desc->pop(); \ + class_desc->pop(); \ + class_desc->add_text(" "); \ + if ((m_message).is_empty()) { \ + class_desc->add_text(m_default_message); \ + } else { \ + _add_text(m_message); \ + } + void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview, bool p_override) { if (p_override) { method_line[p_method.name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description. @@ -439,7 +476,7 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview _add_type(p_method.return_type, p_method.return_enum, p_method.return_is_bitfield); if (p_overview) { - class_desc->pop(); // align + class_desc->pop(); // paragraph class_desc->pop(); // cell class_desc->push_cell(); } else { @@ -451,8 +488,8 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview } class_desc->push_color(theme_cache.headline_color); - _add_text(p_method.name); - class_desc->pop(); + class_desc->add_text(p_method.name); + class_desc->pop(); // color if (p_overview && !p_method.description.strip_edges().is_empty()) { class_desc->pop(); // meta @@ -460,7 +497,7 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("("); - class_desc->pop(); + class_desc->pop(); // color for (int j = 0; j < p_method.arguments.size(); j++) { class_desc->push_color(theme_cache.text_color); @@ -468,35 +505,38 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview class_desc->add_text(", "); } - _add_text(p_method.arguments[j].name); + class_desc->add_text(p_method.arguments[j].name); class_desc->add_text(": "); _add_type(p_method.arguments[j].type, p_method.arguments[j].enumeration, p_method.arguments[j].is_bitfield); + if (!p_method.arguments[j].default_value.is_empty()) { class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" = "); - class_desc->pop(); + class_desc->pop(); // color + class_desc->push_color(theme_cache.value_color); class_desc->add_text(_fix_constant(p_method.arguments[j].default_value)); - class_desc->pop(); + class_desc->pop(); // color } - class_desc->pop(); + class_desc->pop(); // color } if (is_vararg) { class_desc->push_color(theme_cache.text_color); - if (p_method.arguments.size()) { + if (!p_method.arguments.is_empty()) { class_desc->add_text(", "); } + class_desc->pop(); // color + class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("..."); - class_desc->pop(); - class_desc->pop(); + class_desc->pop(); // color } class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(")"); - class_desc->pop(); + class_desc->pop(); // color if (!p_method.qualifiers.is_empty()) { class_desc->push_color(theme_cache.qualifier_color); @@ -517,23 +557,26 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview if (!hint.is_empty()) { class_desc->push_hint(hint); class_desc->add_text(qualifier); - class_desc->pop(); + class_desc->pop(); // hint } else { class_desc->add_text(qualifier); } } - class_desc->pop(); - } - if (p_method.is_deprecated) { - DEPRECATED_DOC_TAG; - } - - if (p_method.is_experimental) { - EXPERIMENTAL_DOC_TAG; + class_desc->pop(); // color } if (p_overview) { + if (p_method.is_deprecated) { + class_desc->add_text(" "); + DEPRECATED_DOC_TAG; + } + + if (p_method.is_experimental) { + class_desc->add_text(" "); + EXPERIMENTAL_DOC_TAG; + } + class_desc->pop(); // cell } } @@ -549,20 +592,20 @@ void EditorHelp::_push_normal_font() { } void EditorHelp::_pop_normal_font() { - class_desc->pop(); - class_desc->pop(); + class_desc->pop(); // font_size + class_desc->pop(); // font } void EditorHelp::_push_title_font() { - class_desc->push_color(theme_cache.title_color); class_desc->push_font(theme_cache.doc_title_font); class_desc->push_font_size(theme_cache.doc_title_font_size); + class_desc->push_color(theme_cache.title_color); } void EditorHelp::_pop_title_font() { - class_desc->pop(); - class_desc->pop(); - class_desc->pop(); + class_desc->pop(); // color + class_desc->pop(); // font_size + class_desc->pop(); // font } void EditorHelp::_push_code_font() { @@ -571,8 +614,8 @@ void EditorHelp::_push_code_font() { } void EditorHelp::_pop_code_font() { - class_desc->pop(); - class_desc->pop(); + class_desc->pop(); // font_size + class_desc->pop(); // font } Error EditorHelp::_goto_desc(const String &p_class) { @@ -596,11 +639,27 @@ Error EditorHelp::_goto_desc(const String &p_class) { return OK; } -void EditorHelp::_update_method_list(const Vector p_methods, MethodType p_method_type) { +void EditorHelp::_update_method_list(MethodType p_method_type, const Vector &p_methods) { + class_desc->add_newline(); + class_desc->add_newline(); + + static const char *titles_by_type[METHOD_TYPE_MAX] = { + TTRC("Methods"), + TTRC("Constructors"), + TTRC("Operators"), + }; + const String title = TTRGET(titles_by_type[p_method_type]); + + section_line.push_back(Pair(title, class_desc->get_paragraph_count() - 2)); + _push_title_font(); + class_desc->add_text(title); + _pop_title_font(); + + class_desc->add_newline(); class_desc->add_newline(); - _push_code_font(); class_desc->push_indent(1); + _push_code_font(); class_desc->push_table(2); class_desc->set_table_column_expand(1, true); @@ -650,18 +709,30 @@ void EditorHelp::_update_method_list(const Vector p_methods, } class_desc->pop(); // table - class_desc->pop(); _pop_code_font(); - - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->pop(); // indent } -void EditorHelp::_update_method_descriptions(const DocData::ClassDoc p_classdoc, const Vector p_methods, MethodType p_method_type) { - String link_color_text = theme_cache.title_color.to_html(false); +void EditorHelp::_update_method_descriptions(const DocData::ClassDoc &p_classdoc, MethodType p_method_type, const Vector &p_methods) { +#define DTR_DOC(m_string) (p_classdoc.is_script_doc ? (m_string) : DTR(m_string)) class_desc->add_newline(); class_desc->add_newline(); + class_desc->add_newline(); + + static const char *titles_by_type[METHOD_TYPE_MAX] = { + TTRC("Method Descriptions"), + TTRC("Constructor Descriptions"), + TTRC("Operator Descriptions"), + }; + const String title = TTRGET(titles_by_type[p_method_type]); + + section_line.push_back(Pair(title, class_desc->get_paragraph_count() - 2)); + _push_title_font(); + class_desc->add_text(title); + _pop_title_font(); + + String link_color_text = theme_cache.title_color.to_html(false); for (int pass = 0; pass < 2; pass++) { Vector methods_filtered; @@ -674,6 +745,10 @@ void EditorHelp::_update_method_descriptions(const DocData::ClassDoc p_classdoc, } for (int i = 0; i < methods_filtered.size(); i++) { + class_desc->add_newline(); + class_desc->add_newline(); + class_desc->add_newline(); + _push_code_font(); // For constructors always point to the first one. _add_method(methods_filtered[i], false, (p_method_type != METHOD_TYPE_CONSTRUCTOR || i == 0)); @@ -682,17 +757,43 @@ void EditorHelp::_update_method_descriptions(const DocData::ClassDoc p_classdoc, class_desc->add_newline(); class_desc->add_newline(); - class_desc->push_color(theme_cache.text_color); - _push_normal_font(); class_desc->push_indent(1); - if (methods_filtered[i].errors_returned.size()) { - class_desc->append_text(TTR("Error codes returned:")); + _push_normal_font(); + class_desc->push_color(theme_cache.text_color); + + if (methods_filtered[i].is_deprecated) { + static const char *messages_by_type[METHOD_TYPE_MAX] = { + TTRC("This method may be changed or removed in future versions."), + TTRC("This constructor may be changed or removed in future versions."), + TTRC("This operator may be changed or removed in future versions."), + }; + DEPRECATED_DOC_MSG(DTR_DOC(methods_filtered[i].deprecated_message), TTRGET(messages_by_type[p_method_type])); + + class_desc->add_newline(); + class_desc->add_newline(); + } + + if (methods_filtered[i].is_experimental) { + static const char *messages_by_type[METHOD_TYPE_MAX] = { + TTRC("This method may be changed or removed in future versions."), + TTRC("This constructor may be changed or removed in future versions."), + TTRC("This operator may be changed or removed in future versions."), + }; + EXPERIMENTAL_DOC_MSG(DTR_DOC(methods_filtered[i].experimental_message), TTRGET(messages_by_type[p_method_type])); + + class_desc->add_newline(); + class_desc->add_newline(); + } + + if (!methods_filtered[i].errors_returned.is_empty()) { + class_desc->add_text(TTR("Error codes returned:")); class_desc->add_newline(); class_desc->push_list(0, RichTextLabel::LIST_DOTS, false); for (int j = 0; j < methods_filtered[i].errors_returned.size(); j++) { if (j > 0) { class_desc->add_newline(); } + int val = methods_filtered[i].errors_returned[j]; String text = itos(val); for (int k = 0; k < CoreConstants::get_global_constant_count(); k++) { @@ -702,21 +803,20 @@ void EditorHelp::_update_method_descriptions(const DocData::ClassDoc p_classdoc, } } - class_desc->push_bold(); - class_desc->append_text(text); - class_desc->pop(); + class_desc->push_font(theme_cache.doc_bold_font); + class_desc->add_text(text); + class_desc->pop(); // font } - class_desc->pop(); + class_desc->pop(); // list + class_desc->add_newline(); class_desc->add_newline(); } - if (!methods_filtered[i].description.strip_edges().is_empty()) { - _add_text(DTR(methods_filtered[i].description)); - } else { - class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); - class_desc->add_text(" "); - class_desc->push_color(theme_cache.comment_color); + const String descr = DTR_DOC(methods_filtered[i].description).strip_edges(); + if (!descr.is_empty()) { + _add_text(descr); + } else { String message; if (p_classdoc.is_script_doc) { static const char *messages_by_type[METHOD_TYPE_MAX] = { @@ -733,19 +833,21 @@ void EditorHelp::_update_method_descriptions(const DocData::ClassDoc p_classdoc, }; message = TTRGET(messages_by_type[p_method_type]).replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text); } + + class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); + class_desc->add_text(" "); + class_desc->push_color(theme_cache.comment_color); class_desc->append_text(message); - class_desc->pop(); + class_desc->pop(); // color } - class_desc->pop(); + class_desc->pop(); // color _pop_normal_font(); - class_desc->pop(); - - class_desc->add_newline(); - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->pop(); // indent } } + +#undef DTR_DOC } void EditorHelp::_update_doc() { @@ -758,46 +860,52 @@ void EditorHelp::_update_doc() { class_desc->clear(); method_line.clear(); section_line.clear(); + section_line.push_back(Pair(TTR("Top"), 0)); String link_color_text = theme_cache.title_color.to_html(false); DocData::ClassDoc cd = doc->class_list[edited_class]; // Make a copy, so we can sort without worrying. +#define DTR_DOC(m_string) (cd.is_script_doc ? (m_string) : DTR(m_string)) + // Class name - section_line.push_back(Pair(TTR("Top"), 0)); + _push_title_font(); + class_desc->add_text(TTR("Class:") + " "); _add_type_icon(edited_class, theme_cache.doc_title_font_size, "Object"); class_desc->add_text(" "); + class_desc->push_color(theme_cache.headline_color); - _add_text(edited_class); + class_desc->add_text(edited_class); class_desc->pop(); // color + _pop_title_font(); if (cd.is_deprecated) { - class_desc->add_text(" "); - Ref error_icon = get_editor_theme_icon(SNAME("StatusError")); - class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); + class_desc->add_newline(); + DEPRECATED_DOC_MSG(DTR_DOC(cd.deprecated_message), TTR("This class may be changed or removed in future versions.")); } + if (cd.is_experimental) { - class_desc->add_text(" "); - Ref warning_icon = get_editor_theme_icon(SNAME("NodeWarning")); - class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); + class_desc->add_newline(); + EXPERIMENTAL_DOC_MSG(DTR_DOC(cd.experimental_message), TTR("This class may be changed or removed in future versions.")); } - class_desc->add_newline(); - - const String non_breaking_space = String::chr(160); // Inheritance tree + const String non_breaking_space = String::chr(160); + // Ascendents if (!cd.inherits.is_empty()) { - class_desc->push_color(theme_cache.title_color); + class_desc->add_newline(); + _push_normal_font(); + class_desc->push_color(theme_cache.title_color); + class_desc->add_text(TTR("Inherits:") + " "); String inherits = cd.inherits; - while (!inherits.is_empty()) { _add_type_icon(inherits, theme_cache.doc_font_size, "ArrowRight"); class_desc->add_text(non_breaking_space); // Otherwise icon borrows hyperlink from _add_type(). @@ -810,13 +918,14 @@ void EditorHelp::_update_doc() { } } + class_desc->pop(); // color _pop_normal_font(); - class_desc->pop(); - class_desc->add_newline(); } // Descendants if ((cd.is_script_doc || ClassDB::class_exists(cd.name)) && doc->inheriting.has(cd.name)) { + class_desc->add_newline(); + _push_normal_font(); class_desc->push_color(theme_cache.title_color); class_desc->add_text(TTR("Inherited by:") + " "); @@ -830,58 +939,40 @@ void EditorHelp::_update_doc() { class_desc->add_text(non_breaking_space); // Otherwise icon borrows hyperlink from _add_type(). _add_type(itr->get()); } - _pop_normal_font(); - - class_desc->pop(); - class_desc->add_newline(); - } - // Note if deprecated. - if (cd.is_deprecated) { - Ref error_icon = get_editor_theme_icon(SNAME("StatusError")); - class_desc->push_color(get_theme_color(SNAME("error_color"), EditorStringName(Editor))); - class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); - class_desc->add_text(String(" ") + TTR("This class is marked as deprecated. It will be removed in future versions.")); - class_desc->pop(); - class_desc->add_newline(); - } - - // Note if experimental. - if (cd.is_experimental) { - Ref warning_icon = get_editor_theme_icon(SNAME("NodeWarning")); - class_desc->push_color(get_theme_color(SNAME("warning_color"), EditorStringName(Editor))); - class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); - class_desc->add_text(String(" ") + TTR("This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion.")); - class_desc->pop(); - class_desc->add_newline(); + class_desc->pop(); // color + _pop_normal_font(); } bool has_description = false; - class_desc->add_newline(); - class_desc->add_newline(); - // Brief description - if (!cd.brief_description.strip_edges().is_empty()) { + const String brief_class_descr = DTR_DOC(cd.brief_description).strip_edges(); + if (!brief_class_descr.is_empty()) { has_description = true; - class_desc->push_color(theme_cache.text_color); - class_desc->push_font(theme_cache.doc_bold_font); - class_desc->push_indent(1); - _add_text(DTR(cd.brief_description)); - class_desc->pop(); - class_desc->pop(); - class_desc->pop(); - - class_desc->add_newline(); class_desc->add_newline(); class_desc->add_newline(); + + class_desc->push_indent(1); + class_desc->push_font(theme_cache.doc_bold_font); + class_desc->push_color(theme_cache.text_color); + + _add_text(brief_class_descr); + + class_desc->pop(); // color + class_desc->pop(); // font + class_desc->pop(); // indent } // Class description - if (!cd.description.strip_edges().is_empty()) { + const String class_descr = DTR_DOC(cd.description).strip_edges(); + if (!class_descr.is_empty()) { has_description = true; + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Description"), class_desc->get_paragraph_count() - 2)); description_line = class_desc->get_paragraph_count() - 2; _push_title_font(); @@ -890,53 +981,64 @@ void EditorHelp::_update_doc() { class_desc->add_newline(); class_desc->add_newline(); - class_desc->push_color(theme_cache.text_color); - _push_normal_font(); + class_desc->push_indent(1); - _add_text(DTR(cd.description)); - class_desc->pop(); + _push_normal_font(); + class_desc->push_color(theme_cache.text_color); + + _add_text(class_descr); + + class_desc->pop(); // color _pop_normal_font(); - class_desc->pop(); + class_desc->pop(); // indent + } + if (!has_description) { class_desc->add_newline(); class_desc->add_newline(); - class_desc->add_newline(); - } - if (!has_description) { + class_desc->push_indent(1); + _push_normal_font(); + class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); class_desc->add_text(" "); - class_desc->push_color(theme_cache.comment_color); + class_desc->push_color(theme_cache.comment_color); if (cd.is_script_doc) { - class_desc->append_text(TTR("There is currently no description for this class.")); + class_desc->add_text(TTR("There is currently no description for this class.")); } else { class_desc->append_text(TTR("There is currently no description for this class. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); } + class_desc->pop(); // color - class_desc->add_newline(); - class_desc->add_newline(); + _pop_normal_font(); + class_desc->pop(); // indent } #ifdef MODULE_MONO_ENABLED if (classes_with_csharp_differences.has(cd.name)) { + class_desc->add_newline(); + class_desc->add_newline(); + const String &csharp_differences_url = vformat("%s/tutorials/scripting/c_sharp/c_sharp_differences.html", VERSION_DOCS_URL); - class_desc->push_color(theme_cache.text_color); - _push_normal_font(); class_desc->push_indent(1); - _add_text("[b]" + TTR("Note:") + "[/b] " + vformat(TTR("There are notable differences when using this API with C#. See [url=%s]C# API differences to GDScript[/url] for more information."), csharp_differences_url)); - class_desc->pop(); - _pop_normal_font(); - class_desc->pop(); + _push_normal_font(); + class_desc->push_color(theme_cache.text_color); - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->append_text("[b]" + TTR("Note:") + "[/b] " + vformat(TTR("There are notable differences when using this API with C#. See [url=%s]C# API differences to GDScript[/url] for more information."), csharp_differences_url)); + + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent } #endif // Online tutorials - if (cd.tutorials.size()) { + if (!cd.tutorials.is_empty()) { + class_desc->add_newline(); + class_desc->add_newline(); + _push_title_font(); class_desc->add_text(TTR("Online Tutorials")); _pop_title_font(); @@ -945,26 +1047,29 @@ void EditorHelp::_update_doc() { class_desc->push_indent(1); _push_code_font(); + class_desc->push_color(theme_cache.symbol_color); for (int i = 0; i < cd.tutorials.size(); i++) { - const String link = DTR(cd.tutorials[i].link); - String linktxt = (cd.tutorials[i].title.is_empty()) ? link : DTR(cd.tutorials[i].title); - const int seppos = linktxt.find("//"); - if (seppos != -1) { - linktxt = link.substr(seppos + 2); + const String link = DTR_DOC(cd.tutorials[i].link).strip_edges(); + + String link_text = DTR_DOC(cd.tutorials[i].title).strip_edges(); + if (link_text.is_empty()) { + const int sep_pos = link.find("//"); + if (sep_pos >= 0) { + link_text = link.substr(sep_pos + 2); + } else { + link_text = link; + } } - class_desc->push_color(theme_cache.symbol_color); - class_desc->append_text("[url=" + link + "]" + linktxt + "[/url]"); - class_desc->pop(); class_desc->add_newline(); + _add_bulletpoint(); + class_desc->append_text("[url=" + link + "]" + link_text + "[/url]"); } + class_desc->pop(); // color _pop_code_font(); - class_desc->pop(); - - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->pop(); // indent } // Properties overview @@ -984,15 +1089,19 @@ void EditorHelp::_update_doc() { } if (has_properties) { + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Properties"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Properties")); _pop_title_font(); + class_desc->add_newline(); class_desc->add_newline(); - _push_code_font(); class_desc->push_indent(1); + _push_code_font(); class_desc->push_table(4); class_desc->set_table_column_expand(1, true); @@ -1006,29 +1115,29 @@ void EditorHelp::_update_doc() { if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.strip_edges().is_empty()) { continue; } + if (is_generating_overridden_properties && !cd.properties[i].overridden) { is_generating_overridden_properties = false; // No need for the extra spacing when there's no overridden property. if (overridden_property_exists) { class_desc->push_cell(); - class_desc->pop(); + class_desc->pop(); // cell class_desc->push_cell(); - class_desc->pop(); + class_desc->pop(); // cell class_desc->push_cell(); - class_desc->pop(); + class_desc->pop(); // cell class_desc->push_cell(); - class_desc->pop(); + class_desc->pop(); // cell } } - property_line[cd.properties[i].name] = class_desc->get_paragraph_count() - 2; //gets overridden if description + + property_line[cd.properties[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description. // Property type. class_desc->push_cell(); class_desc->push_paragraph(HORIZONTAL_ALIGNMENT_RIGHT, Control::TEXT_DIRECTION_AUTO, ""); - _push_code_font(); _add_type(cd.properties[i].type, cd.properties[i].enumeration, cd.properties[i].is_bitfield); - _pop_code_font(); - class_desc->pop(); + class_desc->pop(); // paragraph class_desc->pop(); // cell bool describe = false; @@ -1052,69 +1161,60 @@ void EditorHelp::_update_doc() { // Property name. class_desc->push_cell(); - _push_code_font(); class_desc->push_color(theme_cache.headline_color); if (describe) { class_desc->push_meta("@member " + cd.properties[i].name); } - _add_text(cd.properties[i].name); + class_desc->add_text(cd.properties[i].name); if (describe) { - class_desc->pop(); + class_desc->pop(); // meta } - class_desc->pop(); - _pop_code_font(); + class_desc->pop(); // color class_desc->pop(); // cell // Property value. class_desc->push_cell(); - _push_code_font(); if (!cd.properties[i].default_value.is_empty()) { if (cd.properties[i].overridden) { class_desc->push_color(theme_cache.override_color); - class_desc->add_text(" ["); - class_desc->push_meta("@member " + cd.properties[i].overrides + "." + cd.properties[i].name); - _add_text(vformat(TTR("overrides %s:"), cd.properties[i].overrides)); - class_desc->pop(); + class_desc->add_text("["); + const String link = vformat("[url=@member %s.%s]%s[/url]", cd.properties[i].overrides, cd.properties[i].name, cd.properties[i].overrides); + class_desc->append_text(vformat(TTR("overrides %s:"), link)); class_desc->add_text(" " + _fix_constant(cd.properties[i].default_value) + "]"); + class_desc->pop(); // color overridden_property_exists = true; } else { class_desc->push_color(theme_cache.symbol_color); - class_desc->add_text(" [" + TTR("default:") + " "); + class_desc->add_text("[" + TTR("default:") + " "); + class_desc->pop(); // color class_desc->push_color(theme_cache.value_color); class_desc->add_text(_fix_constant(cd.properties[i].default_value)); - class_desc->pop(); + class_desc->pop(); // color class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("]"); - class_desc->pop(); + class_desc->pop(); // color } - class_desc->pop(); // color - } - - if (cd.properties[i].is_deprecated) { - DEPRECATED_DOC_TAG; } - if (cd.properties[i].is_experimental) { - EXPERIMENTAL_DOC_TAG; - } - - _pop_code_font(); class_desc->pop(); // cell - // Property setters and getters. + // Property setter/getter and deprecated/experimental marks. class_desc->push_cell(); - _push_code_font(); + + bool has_prev_text = false; if (cd.is_script_doc && (!cd.properties[i].setter.is_empty() || !cd.properties[i].getter.is_empty())) { + has_prev_text = true; + class_desc->push_color(theme_cache.symbol_color); - class_desc->add_text(" [" + TTR("property:") + " "); + class_desc->add_text("[" + TTR("property:") + " "); class_desc->pop(); // color if (!cd.properties[i].setter.is_empty()) { @@ -1138,16 +1238,28 @@ void EditorHelp::_update_doc() { class_desc->pop(); // color } - _pop_code_font(); + if (cd.properties[i].is_deprecated) { + if (has_prev_text) { + class_desc->add_text(" "); + } + has_prev_text = true; + DEPRECATED_DOC_TAG; + } + + if (cd.properties[i].is_experimental) { + if (has_prev_text) { + class_desc->add_text(" "); + } + has_prev_text = true; + EXPERIMENTAL_DOC_TAG; + } + class_desc->pop(); // cell } class_desc->pop(); // table - class_desc->pop(); _pop_code_font(); - - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->pop(); // indent } // Methods overview @@ -1172,53 +1284,33 @@ void EditorHelp::_update_doc() { if (sort_methods) { cd.constructors.sort(); } - - section_line.push_back(Pair(TTR("Constructors"), class_desc->get_paragraph_count() - 2)); - _push_title_font(); - class_desc->add_text(TTR("Constructors")); - _pop_title_font(); - - _update_method_list(cd.constructors, METHOD_TYPE_CONSTRUCTOR); + _update_method_list(METHOD_TYPE_CONSTRUCTOR, cd.constructors); } if (!methods.is_empty()) { if (sort_methods) { methods.sort(); } - - section_line.push_back(Pair(TTR("Methods"), class_desc->get_paragraph_count() - 2)); - _push_title_font(); - class_desc->add_text(TTR("Methods")); - _pop_title_font(); - - _update_method_list(methods, METHOD_TYPE_METHOD); + _update_method_list(METHOD_TYPE_METHOD, methods); } if (!cd.operators.is_empty()) { if (sort_methods) { cd.operators.sort(); } - - section_line.push_back(Pair(TTR("Operators"), class_desc->get_paragraph_count() - 2)); - _push_title_font(); - class_desc->add_text(TTR("Operators")); - _pop_title_font(); - - _update_method_list(cd.operators, METHOD_TYPE_OPERATOR); + _update_method_list(METHOD_TYPE_OPERATOR, cd.operators); } // Theme properties if (!cd.theme_properties.is_empty()) { + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Theme Properties"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Theme Properties")); _pop_title_font(); - class_desc->add_newline(); - class_desc->add_newline(); - - class_desc->push_indent(1); - String theme_data_type; HashMap data_type_names; data_type_names["color"] = TTR("Colors"); @@ -1229,23 +1321,32 @@ void EditorHelp::_update_doc() { data_type_names["style"] = TTR("Styles"); for (int i = 0; i < cd.theme_properties.size(); i++) { - theme_property_line[cd.theme_properties[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description. - if (theme_data_type != cd.theme_properties[i].data_type) { theme_data_type = cd.theme_properties[i].data_type; + class_desc->add_newline(); + class_desc->add_newline(); + + class_desc->push_indent(1); _push_title_font(); + if (data_type_names.has(theme_data_type)) { class_desc->add_text(data_type_names[theme_data_type]); } else { - class_desc->add_text(""); + class_desc->add_text(theme_data_type); } - _pop_title_font(); - class_desc->add_newline(); - class_desc->add_newline(); + _pop_title_font(); + class_desc->pop(); // indent } + class_desc->add_newline(); + class_desc->add_newline(); + + theme_property_line[cd.theme_properties[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description. + + class_desc->push_indent(1); + // Theme item header. _push_code_font(); _add_bulletpoint(); @@ -1256,41 +1357,52 @@ void EditorHelp::_update_doc() { // Theme item name. class_desc->push_color(theme_cache.headline_color); class_desc->add_text(" "); - _add_text(cd.theme_properties[i].name); - class_desc->pop(); + class_desc->add_text(cd.theme_properties[i].name); + class_desc->pop(); // color // Theme item default value. if (!cd.theme_properties[i].default_value.is_empty()) { class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" [" + TTR("default:") + " "); - class_desc->pop(); + class_desc->pop(); // color + class_desc->push_color(theme_cache.value_color); class_desc->add_text(_fix_constant(cd.theme_properties[i].default_value)); - class_desc->pop(); + class_desc->pop(); // color + class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("]"); - class_desc->pop(); + class_desc->pop(); // color } _pop_code_font(); // Theme item description. - if (!cd.theme_properties[i].description.strip_edges().is_empty()) { + class_desc->push_indent(1); + _push_normal_font(); + class_desc->push_color(theme_cache.comment_color); + + const String descr = DTR_DOC(cd.theme_properties[i].description).strip_edges(); + if (!descr.is_empty()) { + _add_text(descr); + } else { + class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); + class_desc->add_text(" "); class_desc->push_color(theme_cache.comment_color); - _push_normal_font(); - class_desc->push_indent(1); - _add_text(DTR(cd.theme_properties[i].description)); - class_desc->pop(); // indent - _pop_normal_font(); + if (cd.is_script_doc) { + class_desc->add_text(TTR("There is currently no description for this theme property.")); + } else { + class_desc->append_text(TTR("There is currently no description for this theme property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); + } class_desc->pop(); // color } - class_desc->add_newline(); - class_desc->add_newline(); - } + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent - class_desc->pop(); - class_desc->add_newline(); + class_desc->pop(); // indent + } } // Signals @@ -1299,76 +1411,111 @@ void EditorHelp::_update_doc() { cd.signals.sort(); } + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Signals"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Signals")); _pop_title_font(); - class_desc->add_newline(); - class_desc->add_newline(); - - class_desc->push_indent(1); - for (int i = 0; i < cd.signals.size(); i++) { + class_desc->add_newline(); + class_desc->add_newline(); + signal_line[cd.signals[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description. + class_desc->push_indent(1); + + // Signal header. _push_code_font(); _add_bulletpoint(); class_desc->push_color(theme_cache.headline_color); - _add_text(cd.signals[i].name); - class_desc->pop(); + class_desc->add_text(cd.signals[i].name); + class_desc->pop(); // color + class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("("); - class_desc->pop(); + class_desc->pop(); // color + for (int j = 0; j < cd.signals[i].arguments.size(); j++) { class_desc->push_color(theme_cache.text_color); + if (j > 0) { class_desc->add_text(", "); } - _add_text(cd.signals[i].arguments[j].name); + class_desc->add_text(cd.signals[i].arguments[j].name); class_desc->add_text(": "); _add_type(cd.signals[i].arguments[j].type, cd.signals[i].arguments[j].enumeration, cd.signals[i].arguments[j].is_bitfield); + + // Signals currently do not support default argument values, neither the core nor GDScript. + // This code is just for completeness. if (!cd.signals[i].arguments[j].default_value.is_empty()) { class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" = "); - class_desc->pop(); - _add_text(cd.signals[i].arguments[j].default_value); + class_desc->pop(); // color + + class_desc->push_color(theme_cache.value_color); + class_desc->add_text(_fix_constant(cd.signals[i].arguments[j].default_value)); + class_desc->pop(); // color } - class_desc->pop(); + class_desc->pop(); // color } class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(")"); + class_desc->pop(); // color + + _pop_code_font(); + + class_desc->add_newline(); + + // Signal description. + class_desc->push_indent(1); + _push_normal_font(); + class_desc->push_color(theme_cache.comment_color); + + const String descr = DTR_DOC(cd.signals[i].description).strip_edges(); + const bool is_multiline = descr.find_char('\n') > 0; if (cd.signals[i].is_deprecated) { - DEPRECATED_DOC_TAG; + DEPRECATED_DOC_MSG(DTR_DOC(cd.signals[i].deprecated_message), TTR("This signal may be changed or removed in future versions.")); + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } } if (cd.signals[i].is_experimental) { - EXPERIMENTAL_DOC_TAG; + EXPERIMENTAL_DOC_MSG(DTR_DOC(cd.signals[i].experimental_message), TTR("This signal may be changed or removed in future versions.")); + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } } - class_desc->pop(); - _pop_code_font(); - - if (!cd.signals[i].description.strip_edges().is_empty()) { + if (!descr.is_empty()) { + _add_text(descr); + } else { + class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); + class_desc->add_text(" "); class_desc->push_color(theme_cache.comment_color); - _push_normal_font(); - class_desc->push_indent(1); - _add_text(DTR(cd.signals[i].description)); - class_desc->pop(); // indent - _pop_normal_font(); + if (cd.is_script_doc) { + class_desc->add_text(TTR("There is currently no description for this signal.")); + } else { + class_desc->append_text(TTR("There is currently no description for this signal. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); + } class_desc->pop(); // color } - class_desc->add_newline(); - class_desc->add_newline(); - } + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent - class_desc->pop(); - class_desc->add_newline(); + class_desc->pop(); // indent + } } // Constants and enums @@ -1404,13 +1551,13 @@ void EditorHelp::_update_doc() { } } if (has_enums) { + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Enumerations"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Enumerations")); _pop_title_font(); - class_desc->push_indent(1); - - class_desc->add_newline(); for (KeyValue> &E : enums) { String key = E.key; @@ -1423,130 +1570,196 @@ void EditorHelp::_update_doc() { } } - enum_line[E.key] = class_desc->get_paragraph_count() - 2; + class_desc->add_newline(); + class_desc->add_newline(); + + // Enum header. _push_code_font(); + enum_line[E.key] = class_desc->get_paragraph_count() - 2; class_desc->push_color(theme_cache.title_color); if (E.value.size() && E.value[0].is_bitfield) { class_desc->add_text("flags "); } else { class_desc->add_text("enum "); } - class_desc->pop(); + class_desc->pop(); // color class_desc->push_color(theme_cache.headline_color); class_desc->add_text(key); - class_desc->pop(); + class_desc->pop(); // color class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(":"); - class_desc->pop(); - - if (cd.enums[key].is_deprecated) { - DEPRECATED_DOC_TAG; - } - if (cd.enums[key].is_experimental) { - EXPERIMENTAL_DOC_TAG; - } + class_desc->pop(); // color _pop_code_font(); - class_desc->add_newline(); - class_desc->add_newline(); - // Enum description. - if (key != "@unnamed_enums" && cd.enums.has(key) && !cd.enums[key].description.strip_edges().is_empty()) { - class_desc->push_color(theme_cache.text_color); - _push_normal_font(); - class_desc->push_indent(1); - _add_text(cd.enums[key].description); - class_desc->pop(); - _pop_normal_font(); - class_desc->pop(); + if (key != "@unnamed_enums" && cd.enums.has(key)) { + const String descr = DTR_DOC(cd.enums[key].description).strip_edges(); + const bool is_multiline = descr.find_char('\n') > 0; + if (cd.enums[key].is_deprecated || cd.enums[key].is_experimental || !descr.is_empty()) { + class_desc->add_newline(); - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->push_indent(1); + _push_normal_font(); + class_desc->push_color(theme_cache.text_color); + + bool has_prev_text = false; + + if (cd.enums[key].is_deprecated) { + has_prev_text = true; + DEPRECATED_DOC_MSG(DTR_DOC(cd.enums[key].deprecated_message), TTR("This enumeration may be changed or removed in future versions.")); + } + + if (cd.enums[key].is_experimental) { + if (has_prev_text) { + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } + } + has_prev_text = true; + EXPERIMENTAL_DOC_MSG(DTR_DOC(cd.enums[key].experimental_message), TTR("This enumeration may be changed or removed in future versions.")); + } + + if (!descr.is_empty()) { + if (has_prev_text) { + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } + } + has_prev_text = true; + _add_text(descr); + } + + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent + } } - class_desc->push_indent(1); Vector enum_list = E.value; + HashMap enum_values; + const int enum_start_line = enum_line[E.key]; - HashMap enumValuesContainer; - int enumStartingLine = enum_line[E.key]; - + bool prev_is_multiline = true; // Use a large margin for the first item. for (int i = 0; i < enum_list.size(); i++) { + const String descr = DTR_DOC(enum_list[i].description).strip_edges(); + const bool is_multiline = descr.find_char('\n') > 0; + + class_desc->add_newline(); + if (prev_is_multiline || is_multiline) { + class_desc->add_newline(); + } + prev_is_multiline = is_multiline; + if (cd.name == "@GlobalScope") { - enumValuesContainer[enum_list[i].name] = enumStartingLine; + enum_values[enum_list[i].name] = enum_start_line; } // Add the enum constant line to the constant_line map so we can locate it as a constant. constant_line[enum_list[i].name] = class_desc->get_paragraph_count() - 2; - _push_code_font(); + class_desc->push_indent(1); + // Enum value header. + _push_code_font(); _add_bulletpoint(); + class_desc->push_color(theme_cache.headline_color); - _add_text(enum_list[i].name); - class_desc->pop(); + class_desc->add_text(enum_list[i].name); + class_desc->pop(); // color + class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" = "); - class_desc->pop(); + class_desc->pop(); // color + class_desc->push_color(theme_cache.value_color); class_desc->add_text(_fix_constant(enum_list[i].value)); - class_desc->pop(); - - if (enum_list[i].is_deprecated) { - DEPRECATED_DOC_TAG; - } - - if (enum_list[i].is_experimental) { - EXPERIMENTAL_DOC_TAG; - } + class_desc->pop(); // color _pop_code_font(); - class_desc->add_newline(); + // Enum value description. + if (enum_list[i].is_deprecated || enum_list[i].is_experimental || !descr.is_empty()) { + class_desc->add_newline(); - if (!enum_list[i].description.strip_edges().is_empty()) { - class_desc->push_color(theme_cache.comment_color); + class_desc->push_indent(1); _push_normal_font(); - _add_text(DTR(enum_list[i].description)); - _pop_normal_font(); - class_desc->pop(); - if (DTR(enum_list[i].description).find("\n") > 0) { - class_desc->add_newline(); + class_desc->push_color(theme_cache.comment_color); + + bool has_prev_text = false; + + if (enum_list[i].is_deprecated) { + has_prev_text = true; + DEPRECATED_DOC_MSG(DTR_DOC(enum_list[i].deprecated_message), TTR("This constant may be changed or removed in future versions.")); + } + + if (enum_list[i].is_experimental) { + if (has_prev_text) { + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } + } + has_prev_text = true; + EXPERIMENTAL_DOC_MSG(DTR_DOC(enum_list[i].experimental_message), TTR("This constant may be changed or removed in future versions.")); + } + + if (!descr.is_empty()) { + if (has_prev_text) { + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } + } + has_prev_text = true; + _add_text(descr); } + + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent } - class_desc->add_newline(); + class_desc->pop(); // indent } if (cd.name == "@GlobalScope") { - enum_values_line[E.key] = enumValuesContainer; + enum_values_line[E.key] = enum_values; } - - class_desc->pop(); - - class_desc->add_newline(); } - - class_desc->pop(); - class_desc->add_newline(); } // Constants - if (constants.size()) { + if (!constants.is_empty()) { + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Constants"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Constants")); _pop_title_font(); - class_desc->push_indent(1); - - class_desc->add_newline(); + bool prev_is_multiline = true; // Use a large margin for the first item. for (int i = 0; i < constants.size(); i++) { + const String descr = DTR_DOC(constants[i].description).strip_edges(); + const bool is_multiline = descr.find_char('\n') > 0; + + class_desc->add_newline(); + if (prev_is_multiline || is_multiline) { + class_desc->add_newline(); + } + prev_is_multiline = is_multiline; + constant_line[constants[i].name] = class_desc->get_paragraph_count() - 2; + class_desc->push_indent(1); + + // Constant header. _push_code_font(); if (constants[i].value.begins_with("Color(") && constants[i].value.ends_with(")")) { @@ -1555,50 +1768,70 @@ void EditorHelp::_update_doc() { if (color.size() >= 3) { class_desc->push_color(Color(color[0], color[1], color[2])); _add_bulletpoint(); - class_desc->pop(); + class_desc->pop(); // color } } else { _add_bulletpoint(); } class_desc->push_color(theme_cache.headline_color); - _add_text(constants[i].name); - class_desc->pop(); + class_desc->add_text(constants[i].name); + class_desc->pop(); // color + class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" = "); - class_desc->pop(); + class_desc->pop(); // color + class_desc->push_color(theme_cache.value_color); class_desc->add_text(_fix_constant(constants[i].value)); - class_desc->pop(); - - if (constants[i].is_deprecated) { - DEPRECATED_DOC_TAG; - } - - if (constants[i].is_experimental) { - EXPERIMENTAL_DOC_TAG; - } + class_desc->pop(); // color _pop_code_font(); - class_desc->add_newline(); + // Constant description. + if (constants[i].is_deprecated || constants[i].is_experimental || !descr.is_empty()) { + class_desc->add_newline(); - if (!constants[i].description.strip_edges().is_empty()) { - class_desc->push_color(theme_cache.comment_color); + class_desc->push_indent(1); _push_normal_font(); - _add_text(DTR(constants[i].description)); - _pop_normal_font(); - class_desc->pop(); - if (DTR(constants[i].description).find("\n") > 0) { - class_desc->add_newline(); + class_desc->push_color(theme_cache.comment_color); + + bool has_prev_text = false; + + if (constants[i].is_deprecated) { + has_prev_text = true; + DEPRECATED_DOC_MSG(DTR_DOC(constants[i].deprecated_message), TTR("This constant may be changed or removed in future versions.")); + } + + if (constants[i].is_experimental) { + if (has_prev_text) { + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } + } + has_prev_text = true; + EXPERIMENTAL_DOC_MSG(DTR_DOC(constants[i].experimental_message), TTR("This constant may be changed or removed in future versions.")); + } + + if (!descr.is_empty()) { + if (has_prev_text) { + class_desc->add_newline(); + if (is_multiline) { + class_desc->add_newline(); + } + } + has_prev_text = true; + _add_text(descr); } + + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent } - class_desc->add_newline(); + class_desc->pop(); // indent } - - class_desc->pop(); - class_desc->add_newline(); } } @@ -1608,112 +1841,126 @@ void EditorHelp::_update_doc() { cd.annotations.sort(); } + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Annotations"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Annotations")); _pop_title_font(); - class_desc->add_newline(); - class_desc->add_newline(); - - class_desc->push_indent(1); - for (int i = 0; i < cd.annotations.size(); i++) { + class_desc->add_newline(); + class_desc->add_newline(); + annotation_line[cd.annotations[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description. + class_desc->push_indent(1); + + // Annotation header. _push_code_font(); _add_bulletpoint(); + class_desc->push_color(theme_cache.headline_color); - _add_text(cd.annotations[i].name); - class_desc->pop(); + class_desc->add_text(cd.annotations[i].name); + class_desc->pop(); // color if (cd.annotations[i].arguments.size() > 0) { class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("("); - class_desc->pop(); + class_desc->pop(); // color + for (int j = 0; j < cd.annotations[i].arguments.size(); j++) { class_desc->push_color(theme_cache.text_color); + if (j > 0) { class_desc->add_text(", "); } - _add_text(cd.annotations[i].arguments[j].name); + class_desc->add_text(cd.annotations[i].arguments[j].name); class_desc->add_text(": "); _add_type(cd.annotations[i].arguments[j].type); + if (!cd.annotations[i].arguments[j].default_value.is_empty()) { class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" = "); - class_desc->pop(); - _add_text(cd.annotations[i].arguments[j].default_value); + class_desc->pop(); // color + + class_desc->push_color(theme_cache.value_color); + class_desc->add_text(_fix_constant(cd.annotations[i].arguments[j].default_value)); + class_desc->pop(); // color } - class_desc->pop(); + class_desc->pop(); // color } if (cd.annotations[i].qualifiers.contains("vararg")) { class_desc->push_color(theme_cache.text_color); - if (cd.annotations[i].arguments.size()) { + if (!cd.annotations[i].arguments.is_empty()) { class_desc->add_text(", "); } + class_desc->pop(); // color + class_desc->push_color(theme_cache.symbol_color); class_desc->add_text("..."); - class_desc->pop(); - class_desc->pop(); + class_desc->pop(); // color } class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(")"); - class_desc->pop(); + class_desc->pop(); // color } if (!cd.annotations[i].qualifiers.is_empty()) { class_desc->push_color(theme_cache.qualifier_color); class_desc->add_text(" "); - _add_text(cd.annotations[i].qualifiers); - class_desc->pop(); + class_desc->add_text(cd.annotations[i].qualifiers); + class_desc->pop(); // color } _pop_code_font(); - if (!cd.annotations[i].description.strip_edges().is_empty()) { - class_desc->push_color(theme_cache.comment_color); - _push_normal_font(); - class_desc->push_indent(1); - _add_text(DTR(cd.annotations[i].description)); - class_desc->pop(); // indent - _pop_normal_font(); - class_desc->pop(); // color + class_desc->add_newline(); + + // Annotation description. + class_desc->push_indent(1); + _push_normal_font(); + class_desc->push_color(theme_cache.comment_color); + + const String descr = DTR_DOC(cd.annotations[i].description).strip_edges(); + if (!descr.is_empty()) { + _add_text(descr); } else { - class_desc->push_indent(1); class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); class_desc->add_text(" "); class_desc->push_color(theme_cache.comment_color); if (cd.is_script_doc) { - class_desc->append_text(TTR("There is currently no description for this annotation.")); + class_desc->add_text(TTR("There is currently no description for this annotation.")); } else { class_desc->append_text(TTR("There is currently no description for this annotation. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); } - class_desc->pop(); - class_desc->pop(); // indent + class_desc->pop(); // color } - class_desc->add_newline(); - class_desc->add_newline(); - } - class_desc->pop(); - class_desc->add_newline(); + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent + + class_desc->pop(); // indent + } } // Property descriptions if (has_property_descriptions) { + class_desc->add_newline(); + class_desc->add_newline(); + class_desc->add_newline(); + section_line.push_back(Pair(TTR("Property Descriptions"), class_desc->get_paragraph_count() - 2)); _push_title_font(); class_desc->add_text(TTR("Property Descriptions")); _pop_title_font(); - class_desc->add_newline(); - class_desc->add_newline(); - for (int i = 0; i < cd.properties.size(); i++) { if (cd.properties[i].overridden) { continue; @@ -1723,6 +1970,10 @@ void EditorHelp::_update_doc() { continue; } + class_desc->add_newline(); + class_desc->add_newline(); + class_desc->add_newline(); + property_line[cd.properties[i].name] = class_desc->get_paragraph_count() - 2; class_desc->push_table(2); @@ -1731,16 +1982,15 @@ void EditorHelp::_update_doc() { class_desc->push_cell(); _push_code_font(); _add_bulletpoint(); - _add_type(cd.properties[i].type, cd.properties[i].enumeration, cd.properties[i].is_bitfield); - class_desc->add_text(" "); _pop_code_font(); class_desc->pop(); // cell class_desc->push_cell(); _push_code_font(); + class_desc->push_color(theme_cache.headline_color); - _add_text(cd.properties[i].name); + class_desc->add_text(cd.properties[i].name); class_desc->pop(); // color if (!cd.properties[i].default_value.is_empty()) { @@ -1757,14 +2007,6 @@ void EditorHelp::_update_doc() { class_desc->pop(); // color } - if (cd.properties[i].is_deprecated) { - DEPRECATED_DOC_TAG; - } - - if (cd.properties[i].is_experimental) { - EXPERIMENTAL_DOC_TAG; - } - if (cd.is_script_doc && (!cd.properties[i].setter.is_empty() || !cd.properties[i].getter.is_empty())) { class_desc->push_color(theme_cache.symbol_color); class_desc->add_text(" [" + TTR("property:") + " "); @@ -1813,7 +2055,7 @@ void EditorHelp::_update_doc() { // Setters with additional arguments are exposed in the method list, so we link them here for quick access. class_desc->push_meta("@method " + cd.properties[i].setter); class_desc->add_text(cd.properties[i].setter + TTR("(value)")); - class_desc->pop(); + class_desc->pop(); // meta } else { class_desc->add_text(cd.properties[i].setter + TTR("(value)")); } @@ -1840,7 +2082,7 @@ void EditorHelp::_update_doc() { // Getters with additional arguments are exposed in the method list, so we link them here for quick access. class_desc->push_meta("@method " + cd.properties[i].getter); class_desc->add_text(cd.properties[i].getter + "()"); - class_desc->pop(); + class_desc->pop(); // meta } else { class_desc->add_text(cd.properties[i].getter + "()"); } @@ -1861,64 +2103,66 @@ void EditorHelp::_update_doc() { class_desc->add_newline(); class_desc->add_newline(); - class_desc->push_color(theme_cache.text_color); - _push_normal_font(); class_desc->push_indent(1); - if (!cd.properties[i].description.strip_edges().is_empty()) { - _add_text(DTR(cd.properties[i].description)); + _push_normal_font(); + class_desc->push_color(theme_cache.text_color); + + if (cd.properties[i].is_deprecated) { + DEPRECATED_DOC_MSG(DTR_DOC(cd.properties[i].deprecated_message), TTR("This property may be changed or removed in future versions.")); + class_desc->add_newline(); + class_desc->add_newline(); + } + + if (cd.properties[i].is_experimental) { + EXPERIMENTAL_DOC_MSG(DTR_DOC(cd.properties[i].experimental_message), TTR("This property may be changed or removed in future versions.")); + class_desc->add_newline(); + class_desc->add_newline(); + } + + const String descr = DTR_DOC(cd.properties[i].description).strip_edges(); + if (!descr.is_empty()) { + _add_text(descr); } else { class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); class_desc->add_text(" "); class_desc->push_color(theme_cache.comment_color); if (cd.is_script_doc) { - class_desc->append_text(TTR("There is currently no description for this property.")); + class_desc->add_text(TTR("There is currently no description for this property.")); } else { class_desc->append_text(TTR("There is currently no description for this property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); } - class_desc->pop(); + class_desc->pop(); // color } - class_desc->pop(); - _pop_normal_font(); - class_desc->pop(); - class_desc->add_newline(); - class_desc->add_newline(); - class_desc->add_newline(); + class_desc->pop(); // color + _pop_normal_font(); + class_desc->pop(); // indent } } // Constructor descriptions if (!cd.constructors.is_empty()) { - section_line.push_back(Pair(TTR("Constructor Descriptions"), class_desc->get_paragraph_count() - 2)); - _push_title_font(); - class_desc->add_text(TTR("Constructor Descriptions")); - _pop_title_font(); - - _update_method_descriptions(cd, cd.constructors, METHOD_TYPE_CONSTRUCTOR); + _update_method_descriptions(cd, METHOD_TYPE_CONSTRUCTOR, cd.constructors); } // Method descriptions if (!methods.is_empty()) { - section_line.push_back(Pair(TTR("Method Descriptions"), class_desc->get_paragraph_count() - 2)); - _push_title_font(); - class_desc->add_text(TTR("Method Descriptions")); - _pop_title_font(); - - _update_method_descriptions(cd, methods, METHOD_TYPE_METHOD); + _update_method_descriptions(cd, METHOD_TYPE_METHOD, methods); } // Operator descriptions if (!cd.operators.is_empty()) { - section_line.push_back(Pair(TTR("Operator Descriptions"), class_desc->get_paragraph_count() - 2)); - _push_title_font(); - class_desc->add_text(TTR("Operator Descriptions")); - _pop_title_font(); - - _update_method_descriptions(cd, cd.operators, METHOD_TYPE_OPERATOR); + _update_method_descriptions(cd, METHOD_TYPE_OPERATOR, cd.operators); } + // Allow the document to be scrolled slightly below the end. + class_desc->add_newline(); + class_desc->add_newline(); + // Free the scroll. scroll_locked = false; + +#undef DTR_DOC } void EditorHelp::_request_help(const String &p_string) { @@ -2081,6 +2325,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control bbcode = bbcode.replace("[codeblock]\n", "[codeblock]"); bbcode = bbcode.replace("[codeblock skip-lint]\n", "[codeblock skip-lint]"); // Extra argument to silence validation warnings. bbcode = bbcode.replace("\n[/codeblock]", "[/codeblock]"); + bbcode = bbcode.replace("[/codeblock]\n", "[/codeblock]"); List tag_stack; bool code_tag = false; @@ -2088,7 +2333,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control int pos = 0; while (pos < bbcode.length()) { - int brk_pos = bbcode.find("[", pos); + int brk_pos = bbcode.find_char('[', pos); if (brk_pos < 0) { brk_pos = bbcode.length(); @@ -2106,7 +2351,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control break; // Nothing else to add. } - int brk_end = bbcode.find("]", brk_pos + 1); + int brk_end = bbcode.find_char(']', brk_pos + 1); if (brk_end == -1) { String text = bbcode.substr(brk_pos, bbcode.length() - brk_pos); @@ -2144,6 +2389,9 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control p_rt->pop(); p_rt->pop(); p_rt->pop(); + if (pos < bbcode.length()) { + p_rt->add_newline(); + } } } code_tag = false; @@ -2154,7 +2402,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control pos = brk_pos + 1; } else if (tag.begins_with("method ") || tag.begins_with("constructor ") || tag.begins_with("operator ") || tag.begins_with("member ") || tag.begins_with("signal ") || tag.begins_with("enum ") || tag.begins_with("constant ") || tag.begins_with("annotation ") || tag.begins_with("theme_item ")) { - const int tag_end = tag.find(" "); + const int tag_end = tag.find_char(' '); const String link_tag = tag.substr(0, tag_end); const String link_target = tag.substr(tag_end + 1, tag.length()).lstrip(" "); @@ -2166,7 +2414,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control Color target_color = link_color; if (link_tag == "method" || link_tag == "constructor" || link_tag == "operator") { target_color = link_method_color; - } else if (link_tag == "member" || link_tag == "signal" || link_tag == "theme property") { + } else if (link_tag == "member" || link_tag == "signal" || link_tag == "theme_item") { target_color = link_property_color; } else if (link_tag == "annotation") { target_color = link_annotation_color; @@ -2182,7 +2430,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control pos = brk_end + 1; } else if (tag.begins_with("param ")) { - const int tag_end = tag.find(" "); + const int tag_end = tag.find_char(' '); const String param_name = tag.substr(tag_end + 1, tag.length()).lstrip(" "); // Use monospace font with translucent background color to make code easier to distinguish from other text. @@ -2298,7 +2546,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control p_rt->add_text("]"); pos = brk_end + 1; } else if (tag == "url") { - int end = bbcode.find("[", brk_end); + int end = bbcode.find_char('[', brk_end); if (end == -1) { end = bbcode.length(); } @@ -2322,7 +2570,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control HashMap bbcode_options; for (int i = 0; i < subtags.size(); i++) { const String &expr = subtags[i]; - int value_pos = expr.find("="); + int value_pos = expr.find_char('='); if (value_pos > -1) { bbcode_options[expr.substr(0, value_pos)] = expr.substr(value_pos + 1).unquote(); } @@ -2343,7 +2591,7 @@ static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, Control } } } - int end = bbcode.find("[", brk_end); + int end = bbcode.find_char('[', brk_end); if (end == -1) { end = bbcode.length(); } @@ -2668,13 +2916,13 @@ DocTools *EditorHelp::get_doc_data() { /// EditorHelpBit /// -void EditorHelpBit::_go_to_help(String p_what) { +void EditorHelpBit::_go_to_help(const String &p_what) { EditorNode::get_singleton()->set_visible_editor(EditorNode::EDITOR_SCRIPT); ScriptEditor::get_singleton()->goto_help(p_what); emit_signal(SNAME("request_hide")); } -void EditorHelpBit::_meta_clicked(String p_select) { +void EditorHelpBit::_meta_clicked(const String &p_select) { if (p_select.begins_with("$")) { // enum String select = p_select.substr(1, p_select.length()); String class_name; @@ -2967,7 +3215,7 @@ void EditorHelpTooltip::parse_tooltip(const String &p_text) { formatted_text = TTR("Signal:"); } else if (type == "theme_item") { description = get_theme_item_description(class_name, property_name); - formatted_text = TTR("Theme Item:"); + formatted_text = TTR("Theme Property:"); } else { ERR_FAIL_MSG("Invalid tooltip type '" + type + "'. Valid types are 'class', 'property', 'method', 'signal', and 'theme_item'."); } diff --git a/editor/editor_help.h b/editor/editor_help.h index 49d13c552281..5018f6570d6a 100644 --- a/editor/editor_help.h +++ b/editor/editor_help.h @@ -179,8 +179,8 @@ class EditorHelp : public VBoxContainer { Error _goto_desc(const String &p_class); //void _update_history_buttons(); - void _update_method_list(const Vector p_methods, MethodType p_method_type); - void _update_method_descriptions(const DocData::ClassDoc p_classdoc, const Vector p_methods, MethodType p_method_type); + void _update_method_list(MethodType p_method_type, const Vector &p_methods); + void _update_method_descriptions(const DocData::ClassDoc &p_classdoc, MethodType p_method_type, const Vector &p_methods); void _update_doc(); void _request_help(const String &p_string); @@ -259,8 +259,8 @@ class EditorHelpBit : public MarginContainer { inline static HashMap> doc_theme_item_cache; RichTextLabel *rich_text = nullptr; - void _go_to_help(String p_what); - void _meta_clicked(String p_select); + void _go_to_help(const String &p_what); + void _meta_clicked(const String &p_select); String text; diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml index 933bfba5bad2..9982edfbd32a 100644 --- a/modules/gdscript/doc_classes/@GDScript.xml +++ b/modules/gdscript/doc_classes/@GDScript.xml @@ -57,12 +57,11 @@ [/codeblock] - + - [i]Deprecated.[/i] Use [method @GlobalScope.type_convert] instead. Converts [param what] to [param type] in the best way possible. The [param type] uses the [enum Variant.Type] values. [codeblock] var a = [4, 2.5, 1.2] diff --git a/modules/gdscript/editor/gdscript_docgen.cpp b/modules/gdscript/editor/gdscript_docgen.cpp index 659140b9b139..601db5414b8d 100644 --- a/modules/gdscript/editor/gdscript_docgen.cpp +++ b/modules/gdscript/editor/gdscript_docgen.cpp @@ -268,7 +268,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ doc.tutorials.append(td); } doc.is_deprecated = p_class->doc_data.is_deprecated; + doc.deprecated_message = p_class->doc_data.deprecated_message; doc.is_experimental = p_class->doc_data.is_experimental; + doc.experimental_message = p_class->doc_data.experimental_message; for (const GDP::ClassNode::Member &member : p_class->members) { switch (member.type) { @@ -295,7 +297,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ const_doc.is_value_valid = true; const_doc.description = m_const->doc_data.description; const_doc.is_deprecated = m_const->doc_data.is_deprecated; + const_doc.deprecated_message = m_const->doc_data.deprecated_message; const_doc.is_experimental = m_const->doc_data.is_experimental; + const_doc.experimental_message = m_const->doc_data.experimental_message; doc.constants.push_back(const_doc); } break; @@ -309,7 +313,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ method_doc.name = func_name; method_doc.description = m_func->doc_data.description; method_doc.is_deprecated = m_func->doc_data.is_deprecated; + method_doc.deprecated_message = m_func->doc_data.deprecated_message; method_doc.is_experimental = m_func->doc_data.is_experimental; + method_doc.experimental_message = m_func->doc_data.experimental_message; method_doc.qualifiers = m_func->is_static ? "static" : ""; if (m_func->return_type) { @@ -349,7 +355,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ signal_doc.name = signal_name; signal_doc.description = m_signal->doc_data.description; signal_doc.is_deprecated = m_signal->doc_data.is_deprecated; + signal_doc.deprecated_message = m_signal->doc_data.deprecated_message; signal_doc.is_experimental = m_signal->doc_data.is_experimental; + signal_doc.experimental_message = m_signal->doc_data.experimental_message; for (const GDScriptParser::ParameterNode *p : m_signal->parameters) { DocData::ArgumentDoc arg_doc; @@ -371,7 +379,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ prop_doc.name = var_name; prop_doc.description = m_var->doc_data.description; prop_doc.is_deprecated = m_var->doc_data.is_deprecated; + prop_doc.deprecated_message = m_var->doc_data.deprecated_message; prop_doc.is_experimental = m_var->doc_data.is_experimental; + prop_doc.experimental_message = m_var->doc_data.experimental_message; _doctype_from_gdtype(m_var->get_datatype(), prop_doc.type, prop_doc.enumeration); switch (m_var->property) { @@ -417,7 +427,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ DocData::EnumDoc enum_doc; enum_doc.description = m_enum->doc_data.description; enum_doc.is_deprecated = m_enum->doc_data.is_deprecated; + enum_doc.deprecated_message = m_enum->doc_data.deprecated_message; enum_doc.is_experimental = m_enum->doc_data.is_experimental; + enum_doc.experimental_message = m_enum->doc_data.experimental_message; doc.enums[name] = enum_doc; for (const GDP::EnumNode::Value &val : m_enum->values) { @@ -428,7 +440,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ const_doc.enumeration = name; const_doc.description = val.doc_data.description; const_doc.is_deprecated = val.doc_data.is_deprecated; + const_doc.deprecated_message = val.doc_data.deprecated_message; const_doc.is_experimental = val.doc_data.is_experimental; + const_doc.experimental_message = val.doc_data.experimental_message; doc.constants.push_back(const_doc); } @@ -448,7 +462,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_ const_doc.enumeration = "@unnamed_enums"; const_doc.description = m_enum_val.doc_data.description; const_doc.is_deprecated = m_enum_val.doc_data.is_deprecated; + const_doc.deprecated_message = m_enum_val.doc_data.deprecated_message; const_doc.is_experimental = m_enum_val.doc_data.is_experimental; + const_doc.experimental_message = m_enum_val.doc_data.experimental_message; doc.constants.push_back(const_doc); } break; diff --git a/modules/gdscript/gdscript_parser.cpp b/modules/gdscript/gdscript_parser.cpp index 649bd735c6a8..46258553293b 100644 --- a/modules/gdscript/gdscript_parser.cpp +++ b/modules/gdscript/gdscript_parser.cpp @@ -3609,11 +3609,17 @@ GDScriptParser::MemberDocData GDScriptParser::parse_doc_comment(int p_line, bool if (state == DOC_LINE_NORMAL) { String stripped_line = doc_line.strip_edges(); - if (stripped_line.begins_with("@deprecated")) { + if (stripped_line == "@deprecated" || stripped_line.begins_with("@deprecated:")) { result.is_deprecated = true; + if (stripped_line.begins_with("@deprecated:")) { + result.deprecated_message = stripped_line.trim_prefix("@deprecated:").strip_edges(); + } continue; - } else if (stripped_line.begins_with("@experimental")) { + } else if (stripped_line == "@experimental" || stripped_line.begins_with("@experimental:")) { result.is_experimental = true; + if (stripped_line.begins_with("@experimental:")) { + result.experimental_message = stripped_line.trim_prefix("@experimental:").strip_edges(); + } continue; } } @@ -3712,11 +3718,17 @@ GDScriptParser::ClassDocData GDScriptParser::parse_class_doc_comment(int p_line, result.tutorials.append(Pair(title, link)); continue; - } else if (stripped_line.begins_with("@deprecated")) { + } else if (stripped_line == "@deprecated" || stripped_line.begins_with("@deprecated:")) { result.is_deprecated = true; + if (stripped_line.begins_with("@deprecated:")) { + result.deprecated_message = stripped_line.trim_prefix("@deprecated:").strip_edges(); + } continue; - } else if (stripped_line.begins_with("@experimental")) { + } else if (stripped_line == "@experimental" || stripped_line.begins_with("@experimental:")) { result.is_experimental = true; + if (stripped_line.begins_with("@experimental:")) { + result.experimental_message = stripped_line.trim_prefix("@experimental:").strip_edges(); + } continue; } } diff --git a/modules/gdscript/gdscript_parser.h b/modules/gdscript/gdscript_parser.h index c064a2d0f46a..6664e6df04f9 100644 --- a/modules/gdscript/gdscript_parser.h +++ b/modules/gdscript/gdscript_parser.h @@ -274,13 +274,17 @@ class GDScriptParser { String description; Vector> tutorials; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; }; struct MemberDocData { String description; bool is_deprecated = false; + String deprecated_message; bool is_experimental = false; + String experimental_message; }; #endif // TOOLS_ENABLED diff --git a/modules/gltf/doc_classes/GLTFDocument.xml b/modules/gltf/doc_classes/GLTFDocument.xml index 1b52a8229818..1f172633da0e 100644 --- a/modules/gltf/doc_classes/GLTFDocument.xml +++ b/modules/gltf/doc_classes/GLTFDocument.xml @@ -10,7 +10,7 @@ $DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html - https://www.khronos.org/files/gltf20-reference-guide.pdf + https://www.khronos.org/files/gltf20-reference-guide.pdf https://registry.khronos.org/glTF/ diff --git a/modules/gltf/doc_classes/GLTFPhysicsBody.xml b/modules/gltf/doc_classes/GLTFPhysicsBody.xml index ca66cd54b041..5cfc22f6b2b9 100644 --- a/modules/gltf/doc_classes/GLTFPhysicsBody.xml +++ b/modules/gltf/doc_classes/GLTFPhysicsBody.xml @@ -55,7 +55,7 @@ The inertia orientation of the physics body. This defines the rotation of the inertia's principle axes relative to the object's local axes. This is only used when the body type is "rigid" or "vehicle" and [member inertia_diagonal] is set to a non-zero value. - + The inertia tensor of the physics body, in kilogram meter squared (kg⋅m²). This is only used when the body type is "rigid" or "vehicle". When converted to a Godot [RigidBody3D] node, if this value is zero, then the inertia will be calculated automatically. diff --git a/modules/gridmap/doc_classes/GridMap.xml b/modules/gridmap/doc_classes/GridMap.xml index 3094a7bf8082..da11cd216f94 100644 --- a/modules/gridmap/doc_classes/GridMap.xml +++ b/modules/gridmap/doc_classes/GridMap.xml @@ -138,11 +138,11 @@ Returns the position of a grid cell in the GridMap's local coordinate space. To convert the returned value into global coordinates, use [method Node3D.to_global]. See also [method map_to_local]. - + - [i]Obsoleted.[/i] Use [signal Resource.changed] instead. + This method does nothing. diff --git a/modules/multiplayer/doc_classes/SceneReplicationConfig.xml b/modules/multiplayer/doc_classes/SceneReplicationConfig.xml index 1a51e4b6e983..8b9203d31604 100644 --- a/modules/multiplayer/doc_classes/SceneReplicationConfig.xml +++ b/modules/multiplayer/doc_classes/SceneReplicationConfig.xml @@ -51,20 +51,18 @@ Returns whether the property identified by the given [param path] is configured to be synchronized on spawn. - + Returns whether the property identified by the given [param path] is configured to be synchronized on process. - [i]Deprecated.[/i] Use [method property_get_replication_mode] instead. - + Returns whether the property identified by the given [param path] is configured to be reliably synchronized when changes are detected on process. - [i]Deprecated.[/i] Use [method property_get_replication_mode] instead. @@ -83,22 +81,20 @@ Sets whether the property identified by the given [param path] is configured to be synchronized on spawn. - + Sets whether the property identified by the given [param path] is configured to be synchronized on process. - [i]Deprecated.[/i] Use [method property_set_replication_mode] with [constant REPLICATION_MODE_ALWAYS] instead. - + Sets whether the property identified by the given [param path] is configured to be reliably synchronized when changes are detected on process. - [i]Deprecated.[/i] Use [method property_set_replication_mode] with [constant REPLICATION_MODE_ON_CHANGE] instead.