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

Add documentation note on Object's boolean context #99091

Merged
merged 1 commit into from
Nov 27, 2024
+1 −0
Merged

Add documentation note on Object's boolean context #99091

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
1 change: 1 addition & 0 deletions doc/classes/Object.xml
View file
Original file line number Diff line number Diff line change
@@ -22,6 +22,7 @@
Lastly, every object can also contain metadata (data about data). [method set_meta] can be useful to store information that the object itself does not depend on. To keep your code clean, making excessive use of metadata is discouraged.
[b]Note:[/b] Unlike references to a [RefCounted], references to an object stored in a variable can become invalid without being set to [code]null[/code]. To check if an object has been deleted, do [i]not[/i] compare it against [code]null[/code]. Instead, use [method @GlobalScope.is_instance_valid]. It's also recommended to inherit from [RefCounted] for classes storing data instead of [Object].
[b]Note:[/b] The [code]script[/code] is not exposed like most properties. To set or get an object's [Script] in code, use [method set_script] and [method get_script], respectively.
[b]Note:[/b] In a boolean context, an [Object] will evaluate to [code]false[/code] if it is equal to [code]null[/code] or it has been freed. Otherwise, an [Object] will always evaluate to [code]true[/code]. See also [method @GlobalScope.is_instance_valid].
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
[b]Note:[/b] In a boolean context, an [Object] will evaluate to [code]false[/code] if it is equal to [code]null[/code] or it has been freed. Otherwise, an [Object] will always evaluate to [code]true[/code]. See also [method @GlobalScope.is_instance_valid].
[b]Note:[/b] In a boolean context, an [Object] will evaluate to [code]false[/code] if it is equal to [code]null[/code] or it is an invalid object (e.g. it has been deleted from memory). Otherwise, an [Object] will always evaluate to [code]true[/code]. See also [method @GlobalScope.is_instance_valid].

Since there is Object#null and for symmetry with is_instance_valid() docs:

godot/doc/classes/@GlobalScope.xml

Line 575 in ec6a1c0

Returns [code]true[/code] if [param instance] is a valid Object (e.g. has not been deleted from memory).

Also, it's worth adding a note to the is_instance_valid() docs that since 4.4 this function is mostly optional in GDScript, you get the same result whether you explicitly or implicitly cast an object to bool.

Copy link
Contributor Author

@Mickeon Mickeon Nov 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Once more there's an ambiguous "e.g." here. Just for clarity, it means less "That would mean" and more "Here's one example of invalid object"? I assume the latter. Either way, I may come up with another way to word it.

Copy link
Member

Choose a reason for hiding this comment

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

Just for clarity, it means less "That would mean" and more "Here's one example of invalid object"? I assume the latter.

Yes, "invalid object" = Object#null | Freed Object.

</description>
<tutorials>
<link title="Object class introduction">$DOCS_URL/contributing/development/core_and_modules/object_class.html</link>