Add detail and code examples to C++ Variant / Array / Dictionary page

[allenwp]

Your Godot version: 4.2.1

Issue description: The C++ documentation for the Variant, Array, TypedArray, and Dictionary classes appears to be lacking the following, which I believe would be useful for those contributing to the engine and for those creating GDExtensions,:

1. Casting conventions
2. How memory management works
3. Code examples

URL to the documentation page (if already existing): https://docs.godotengine.org/en/stable/contributing/development/core_and_modules/variant_class.html

Proposal

Variant Variant code examples could include how to correctly cast to different types, such as how to get an Array or Object (Node, etc.) from a Variant. I believe that having these casting examples will help users, like myself, more quickly get a good understanding of how the Variant class should be used in C++ code.

Array, TypedArray, and Dictionary I think it would be valuable to explain that these classes internally create a reference counted object, but should not be used with Ref<> because they do not inherit from RefCounted. Most importantly, I think it would be very valuable to have some memory management code examples that show how "Modifications to a container will modify all references to it." and how the Array (etc.) will be freed from memory once it goes out of scope.

These additional examples and descriptions are especially valuable in the context of other existing documentation pages that describe how memnew should be used on Objects and how Ref<> should be used with RefCounted objects. It was surprising to me, as I read the current documentation, that these idioms do not seem to apply to Variant, Array, TypedArray, and Dictionary`.

Discussion

It is entirely possible that I have overlooked a critical section of the documentation that outlines these details.

I think that it is also important to note that memory management, code examples, and reference counting behaviour of other classes is well documented on the following two pages: https://docs.godotengine.org/en/stable/contributing/development/core_and_modules/core_types.html https://docs.godotengine.org/en/stable/contributing/development/core_and_modules/object_class.html

For this reason, I believe that it is only Variant, Array, TypedArray, and Dictionary classes that need additional documentation.

[migueldeicaza]

In the context of GDExtension, it would be useful to know what are the ownership rules for both Ref/RefCounted and Variant objects in the following conditions.

Something similar to this:

https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html

In a language binding using GDExtension, I take for granted that when I create a Variant, I own the destruction of that Variant. And I am taking for granted that if I call into Godot, that they will not release the Variant at all.

What is not clear to me when copies of Variants need to be made in the following scenarios:

• When a variant is included on the signal, do I own the variant that is received?
• When a variant is sent as an argument to a virtual method, do I need to make a copy of it, or do am I getting the ownership of it?

I think that a similar scenario exists for RefCounted objects, I have an instinct as to who owns the object, and when I have to reference count, but the rules are not spelled out in either the Godot source code, nor its documentation.

[allenwp]

When looking through some old issues, I noticed #7248 has some notes that are related to this issue.