Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update many Deprecated/Experimental descriptions for consistency #88443

Merged
merged 1 commit into from
Feb 20, 2024
+63 −51
Merged

Update many Deprecated/Experimental descriptions for consistency #88443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions doc/classes/@GlobalScope.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2889,7 +2889,7 @@
[/codeblocks]
[b]Note:[/b] The trailing colon is required for properly detecting built-in types.
</constant>
<constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="24" enum="PropertyHint" deprecated="This hint is not used anywhere and will be removed in the future.">
<constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="24" enum="PropertyHint" deprecated="This hint is not used by the engine.">
</constant>
<constant name="PROPERTY_HINT_OBJECT_TOO_BIG" value="25" enum="PropertyHint">
Hints that an object is too big to be sent via the debugger.
Expand All @@ -2903,7 +2903,7 @@
<constant name="PROPERTY_HINT_GLOBAL_SAVE_FILE" value="28" enum="PropertyHint">
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].
</constant>
<constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="29" enum="PropertyHint" deprecated="This hint is not used anywhere and will be removed in the future.">
<constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="29" enum="PropertyHint" deprecated="This hint is not used by the engine.">
</constant>
<constant name="PROPERTY_HINT_INT_IS_POINTER" value="30" enum="PropertyHint">
Hints that an [int] property is a pointer. Used by GDExtension.
Expand Down Expand Up @@ -2974,7 +2974,7 @@
<constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="16384" enum="PropertyUsageFlags" is_bitfield="true">
If this property is modified, all inspector fields will be refreshed.
</constant>
<constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This hint is not used anywhere and will be removed in the future.">
<constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This flag is not used by the engine.">
</constant>
<constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="65536" enum="PropertyUsageFlags" is_bitfield="true">
The property is an enum, i.e. it only takes named integer constants from its associated enumeration.
Expand Down Expand Up @@ -3003,7 +3003,7 @@
<constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="16777216" enum="PropertyUsageFlags" is_bitfield="true">
Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row.
</constant>
<constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This hint is not used anywhere and will be removed in the future.">
<constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This flag is not used by the engine.">
</constant>
<constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="67108864" enum="PropertyUsageFlags" is_bitfield="true">
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.
Expand Down
2 changes: 1 addition & 1 deletion doc/classes/AnimatedTexture.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimatedTexture" inherits="Texture2D" deprecated="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<class name="AnimatedTexture" inherits="Texture2D" deprecated="This class does not work properly in current versions and may be removed in the future. There is currently no equivalent workaround." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Proxy texture for simple frame-based animations.
</brief_description>
Expand Down
4 changes: 2 additions & 2 deletions doc/classes/AnimationMixer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@
To make the blended results look good, it is recommended to set this to [constant ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS] to update every frame during blending. Other values exist for compatibility and they are fine if there is no blending, but not so, may produce artifacts.
</member>
<member name="callback_mode_method" type="int" setter="set_callback_mode_method" getter="get_callback_mode_method" enum="AnimationMixer.AnimationCallbackModeMethod" default="0">
The call mode to use for Call Method tracks.
The call mode used for "Call Method" tracks.
</member>
<member name="callback_mode_process" type="int" setter="set_callback_mode_process" getter="get_callback_mode_process" enum="AnimationMixer.AnimationCallbackModeProcess" default="1">
The process notification in which to update animations.
Expand All @@ -301,7 +301,7 @@
If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D] or [constant Animation.TYPE_SCALE_3D] the transformation will be canceled visually, and the animation will appear to stay in place. See also [method get_root_motion_position], [method get_root_motion_rotation], [method get_root_motion_scale] and [RootMotionView].
</member>
<member name="root_node" type="NodePath" setter="set_root_node" getter="get_root_node" default="NodePath(&quot;..&quot;)">
The node from which node path references will travel.
The node which node path references will travel from.
</member>
</members>
<signals>
Expand Down
6 changes: 6 additions & 0 deletions doc/classes/AnimationPlayer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
<method name="get_method_call_mode" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_method] instead.">
<return type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
<description>
Returns the call mode used for "Call Method" tracks.
</description>
</method>
<method name="get_playing_speed" qualifiers="const">
Expand All @@ -59,6 +60,7 @@
<method name="get_process_callback" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="int" enum="AnimationPlayer.AnimationProcessCallback" />
<description>
Returns the process notification in which to update animations.
</description>
</method>
<method name="get_queue">
Expand All @@ -70,6 +72,7 @@
<method name="get_root" qualifiers="const" deprecated="Use [member AnimationMixer.root_node] instead.">
<return type="NodePath" />
<description>
Returns the node which node path references will travel from.
</description>
</method>
<method name="is_playing" qualifiers="const">
Expand Down Expand Up @@ -159,18 +162,21 @@
<return type="void" />
<param index="0" name="mode" type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
<description>
Sets the call mode used for "Call Method" tracks.
</description>
</method>
<method name="set_process_callback" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="void" />
<param index="0" name="mode" type="int" enum="AnimationPlayer.AnimationProcessCallback" />
<description>
Sets the process notification in which to update animations.
</description>
</method>
<method name="set_root" deprecated="Use [member AnimationMixer.root_node] instead.">
<return type="void" />
<param index="0" name="path" type="NodePath" />
<description>
Sets the node which node path references will travel from.
</description>
</method>
<method name="stop">
Expand Down
2 changes: 2 additions & 0 deletions doc/classes/AnimationTree.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,14 @@
<method name="get_process_callback" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="int" enum="AnimationTree.AnimationProcessCallback" />
<description>
Returns the process notification in which to update animations.
</description>
</method>
<method name="set_process_callback" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="void" />
<param index="0" name="mode" type="int" enum="AnimationTree.AnimationProcessCallback" />
<description>
Sets the process notification in which to update animations.
</description>
</method>
</methods>
Expand Down
4 changes: 2 additions & 2 deletions doc/classes/Control.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1158,12 +1158,12 @@
[b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification.
See also [constant NOTIFICATION_MOUSE_EXIT_SELF].
</constant>
<constant name="NOTIFICATION_MOUSE_ENTER_SELF" value="60" experimental="">
<constant name="NOTIFICATION_MOUSE_ENTER_SELF" value="60" experimental="The reason this notification is sent may change in the future.">
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].
</constant>
<constant name="NOTIFICATION_MOUSE_EXIT_SELF" value="61" experimental="">
<constant name="NOTIFICATION_MOUSE_EXIT_SELF" value="61" experimental="The reason this notification is sent may change in the future.">
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].
Expand Down
4 changes: 2 additions & 2 deletions doc/classes/HTTPClient.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -322,10 +322,10 @@
<constant name="RESPONSE_NOT_MODIFIED" value="304" enum="ResponseCode">
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].
</constant>
<constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" deprecated="">
<constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard.">
HTTP status code [code]305 Use Proxy[/code].
</constant>
<constant name="RESPONSE_SWITCH_PROXY" value="306" enum="ResponseCode" deprecated="">
<constant name="RESPONSE_SWITCH_PROXY" value="306" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard.">
HTTP status code [code]306 Switch Proxy[/code].
</constant>
<constant name="RESPONSE_TEMPORARY_REDIRECT" value="307" enum="ResponseCode">
Expand Down
2 changes: 1 addition & 1 deletion doc/classes/LightmapGIData.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@
</method>
</methods>
<members>
<member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture" deprecated="The lightmap atlas can now have multiple textures. See [member lightmap_textures].">
<member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture" deprecated="The lightmap atlas can now contain multiple textures. See [member lightmap_textures].">
The lightmap atlas texture generated by the lightmapper.
</member>
<member name="lightmap_textures" type="TextureLayered[]" setter="set_lightmap_textures" getter="get_lightmap_textures" default="[]">
Expand Down
13 changes: 8 additions & 5 deletions doc/classes/MultiMesh.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,13 +90,14 @@
<members>
<member name="buffer" type="PackedFloat32Array" setter="set_buffer" getter="get_buffer" default="PackedFloat32Array()">
</member>
<member name="color_array" type="PackedColorArray" setter="_set_color_array" getter="_get_color_array" deprecated="Use [method set_instance_color] instead.">
<member name="color_array" type="PackedColorArray" setter="_set_color_array" getter="_get_color_array" deprecated="Accessing this property is very slow. Use [method set_instance_color] and [method get_instance_color] instead.">
Array containing each [Color] used by all instances of this mesh.
</member>
<member name="custom_aabb" type="AABB" setter="set_custom_aabb" getter="get_custom_aabb" default="AABB(0, 0, 0, 0, 0, 0)">
Custom AABB for this MultiMesh resource. Setting this manually prevents costly runtime AABB recalculations.
</member>
<member name="custom_data_array" type="PackedColorArray" setter="_set_custom_data_array" getter="_get_custom_data_array" deprecated="Use [method set_instance_custom_data] instead.">
See [method set_instance_custom_data].
<member name="custom_data_array" type="PackedColorArray" setter="_set_custom_data_array" getter="_get_custom_data_array" deprecated="Accessing this property is very slow. Use [method set_instance_custom_data] and [method get_instance_custom_data] instead.">
Array containing each custom data value used by all instances of this mesh, as a [PackedColorArray].
</member>
<member name="instance_count" type="int" setter="set_instance_count" getter="get_instance_count" default="0">
Number of instances that will get drawn. This clears and (re)sizes the buffers. Setting data format or flags afterwards will have no effect.
Expand All @@ -106,9 +107,11 @@
[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].
</member>
<member name="transform_2d_array" type="PackedVector2Array" setter="_set_transform_2d_array" getter="_get_transform_2d_array" deprecated="Use [method set_instance_transform_2d] instead.">
<member name="transform_2d_array" type="PackedVector2Array" setter="_set_transform_2d_array" getter="_get_transform_2d_array" deprecated="Accessing this property is very slow. Use [method set_instance_transform_2d] and [method get_instance_transform_2d] instead.">
Array containing each [Transform2D] value used by all instances of this mesh, as a [PackedVector2Array]. Each transform is divided into 3 [Vector2] values corresponding to the transforms' [code]x[/code], [code]y[/code], and [code]origin[/code].
</member>
<member name="transform_array" type="PackedVector3Array" setter="_set_transform_array" getter="_get_transform_array" deprecated="Use [method set_instance_transform] instead.">
<member name="transform_array" type="PackedVector3Array" setter="_set_transform_array" getter="_get_transform_array" deprecated="Accessing this property is very slow. Use [method set_instance_transform] and [method get_instance_transform] instead.">
Array containing each [Transform3D] value used by all instances of this mesh, as a [PackedVector3Array]. Each transform is divided into 4 [Vector3] values corresponding to the transforms' [code]x[/code], [code]y[/code], [code]z[/code], and [code]origin[/code].
</member>
<member name="transform_format" type="int" setter="set_transform_format" getter="get_transform_format" enum="MultiMesh.TransformFormat" default="0">
Format of transform used to transform mesh, either 2D or 3D.
Expand Down
4 changes: 2 additions & 2 deletions doc/classes/NavigationMeshGenerator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@
<link title="Using NavigationMeshes">$DOCS_URL/tutorials/navigation/navigation_using_navigationmeshes.html</link>
</tutorials>
<methods>
<method name="bake" deprecated="">
<method name="bake" deprecated="This method 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.">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion, the message should be as short as possible, details should be placed in the description. In the future we might use deprecated/experimental messages for warnings in GDScript and C#.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do agree a lot, but I also wanted to keep my reasoning consistent in the PR. "Why", then "provide alternative". So moving it in the description would go against that.

<return type="void" />
<param index="0" name="navigation_mesh" type="NavigationMesh" />
<param index="1" name="root_node" type="Node" />
<description>
The bake 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.
Bakes the [param navigation_mesh] with source geometry collected starting from the [param root_node].
</description>
</method>
<method name="bake_from_source_geometry_data">
Expand Down
3 changes: 1 addition & 2 deletions doc/classes/NavigationServer3D.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -886,13 +886,12 @@
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.
</description>
</method>
<method name="region_bake_navigation_mesh" deprecated="This method is deprecated due to core threading changes.">
<method name="region_bake_navigation_mesh" deprecated="This method 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.">
<return type="void" />
<param index="0" name="navigation_mesh" type="NavigationMesh" />
<param index="1" name="root_node" type="Node" />
<description>
Bakes the [param navigation_mesh] with bake source geometry collected starting from the [param root_node].
[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.
</description>
</method>
<method name="region_create">
Expand Down
3 changes: 1 addition & 2 deletions doc/classes/Node.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1068,8 +1068,7 @@
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.
</constant>
<constant name="NOTIFICATION_MOVED_IN_PARENT" value="12" deprecated="Use [constant NOTIFICATION_CHILD_ORDER_CHANGED] instead.">
This notification is no longer emitted.
<constant name="NOTIFICATION_MOVED_IN_PARENT" value="12" deprecated="This notification is no longer sent by the engine. Use [constant NOTIFICATION_CHILD_ORDER_CHANGED] instead.">
</constant>
<constant name="NOTIFICATION_READY" value="13">
Notification received when the node is ready. See [method _ready].
Expand Down
5 changes: 5 additions & 0 deletions doc/classes/RenderingDevice.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
<param index="0" name="from" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" />
<param index="1" name="to" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" />
<description>
This method does nothing.
</description>
</method>
<method name="buffer_clear">
Expand Down Expand Up @@ -194,6 +195,7 @@
<param index="0" name="name" type="String" />
<param index="1" name="color" type="Color" />
<description>
This method does nothing.
</description>
</method>
<method name="draw_list_begin">
Expand Down Expand Up @@ -254,6 +256,7 @@
<param index="9" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" />
<param index="10" name="storage_textures" type="RID[]" default="[]" />
<description>
This method does nothing and always returns an empty [PackedInt64Array].
</description>
</method>
<method name="draw_list_bind_index_array">
Expand Down Expand Up @@ -348,6 +351,7 @@
<return type="PackedInt64Array" />
<param index="0" name="splits" type="int" />
<description>
This method does nothing and always returns an empty [PackedInt64Array].
</description>
</method>
<method name="framebuffer_create">
Expand Down Expand Up @@ -438,6 +442,7 @@
<method name="full_barrier" deprecated="Barriers are automatically inserted by RenderingDevice.">
<return type="void" />
<description>
This method does nothing.
</description>
</method>
<method name="get_captured_timestamp_cpu_time" qualifiers="const">
Expand Down
Loading
Loading