From b717a61903cd7c5a1eac8bc243d67204f404b7ba Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 27 Jul 2020 09:59:02 +0200 Subject: [PATCH] Improve the Object, Reference and Resource class documentations (cherry picked from commit 4275e6aad53c0662c208c899ebcadd1d7b3cbbaa) --- doc/classes/Object.xml | 4 +++- doc/classes/Reference.xml | 3 ++- doc/classes/Resource.xml | 5 +++-- doc/classes/String.xml | 2 +- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 59d4f47ba57..7c5b676cf22 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -17,8 +17,10 @@ [/codeblock] The [code]in[/code] operator will evaluate to [code]true[/code] as long as the key exists, even if the value is [code]null[/code]. Objects also receive notifications. Notifications are a simple way to notify the object about different events, so they can all be handled together. See [method _notification]. + [b]Note:[/b] Unlike references to a [Reference], references to an Object stored in a variable can become invalid without warning. Therefore, it's recommended to use [Reference] for data classes instead of [Object]. + https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html @@ -521,7 +523,7 @@ One-shot connections disconnect themselves after emission. - Connect a signal as reference counted. This means that a given signal can be connected several times to the same target, and will only be fully disconnected once no references are left. + Connect a signal as reference-counted. This means that a given signal can be connected several times to the same target, and will only be fully disconnected once no references are left. diff --git a/doc/classes/Reference.xml b/doc/classes/Reference.xml index 23623fb46f9..5dc4b468a11 100644 --- a/doc/classes/Reference.xml +++ b/doc/classes/Reference.xml @@ -5,10 +5,11 @@ Base class for any object that keeps a reference count. [Resource] and many other helper objects inherit this class. - References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with [method Object.free]. + Unlike [Object]s, References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with [method Object.free]. In the vast majority of use cases, instantiating and using [Reference]-derived types is all you need to do. The methods provided in this class are only for advanced users, and can cause issues if misused. + https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 1904a15ceec..b1df9db2673 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -4,10 +4,11 @@ Base class for all resources. - Resource is the base class for all Godot-specific resource types, serving primarily as data containers. They are reference counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. + Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Unlike [Object]s, they are reference-counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference-counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. - https://docs.godotengine.org/en/latest/getting_started/step_by_step/resources.html + https://docs.godotengine.org/en/latest/getting_started/step_by_step/resources.html + https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 3aa56a0e502..5e197cea0fa 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -4,7 +4,7 @@ Built-in string class. - This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference counted and use a copy-on-write approach, so passing them around is cheap in resources. + This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference-counted and use a copy-on-write approach, so passing them around is cheap in resources. https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_format_string.html