From 4275e6aad53c0662c208c899ebcadd1d7b3cbbaa 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 --- 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 3d8c2c5eb0e..ca6b624359d 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 @@ -518,7 +520,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 860a47798c1..9c3d1d5d9d0 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 0aa40dffb35..e79a2e0ea93 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 71db03e84f2..7e55f8bd9a3 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