godotengine / godotengine/godot-docs

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

Open
#8,835 2 comments 0 reactions 0 assignees View on GitHub
enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.