godotengine / godotengine/godot-docs
Add detail and code examples to C++ Variant / Array / Dictionary page
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.