From b6dcb111d2ff2ff9c5fb9c66785977120ce34b4d Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Tue, 3 Jun 2025 02:23:12 +0200
Subject: [PATCH] Document typed dictionaries and arrays in the class reference

---
 doc/classes/Array.xml      | 10 +++++++++-
 doc/classes/Dictionary.xml | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 98c9e7c7910..b1d784003e3 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -4,7 +4,7 @@
 		A built-in data structure that holds a sequence of elements.
 	</brief_description>
 	<description>
-		An array data structure that can contain a sequence of elements of any [Variant] type. Elements are accessed by a numerical index starting at [code]0[/code]. Negative indices are used to count from the back ([code]-1[/code] is the last element, [code]-2[/code] is the second to last, etc.).
+		An array data structure that can contain a sequence of elements of any [Variant] type by default. Values can optionally be constrained to a specific type by creating a [i]typed array[/i]. Elements are accessed by a numerical index starting at [code]0[/code]. Negative indices are used to count from the back ([code]-1[/code] is the last element, [code]-2[/code] is the second to last, etc.).
 		[codeblocks]
 		[gdscript]
 		var array = ["First", 2, 3, "Last"]
@@ -15,6 +15,10 @@
 		array[1] = "Second"
 		print(array[1])  # Prints "Second"
 		print(array[-3]) # Prints "Second"
+
+		# This typed array can only contain integers.
+		# Attempting to add any other type will result in an error.
+		var typed_array: Array[int] = [1, 2, 3]
 		[/gdscript]
 		[csharp]
 		Godot.Collections.Array array = ["First", 2, 3, "Last"];
@@ -25,6 +29,10 @@
 		array[1] = "Second";
 		GD.Print(array[1]); // Prints "Second"
 		GD.Print(array[^3]); // Prints "Second"
+
+		// This typed array can only contain integers.
+		// Attempting to add any other type will result in an error.
+		Godot.Collections.Array&gt;int&lt; typedArray = [1, 2, 3];
 		[/csharp]
 		[/codeblocks]
 		[b]Note:[/b] Arrays are always passed by [b]reference[/b]. To get a copy of an array that can be modified independently of the original array, use [method duplicate].
diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml
index d26b4e0307c..1b4016dfdff 100644
--- a/doc/classes/Dictionary.xml
+++ b/doc/classes/Dictionary.xml
@@ -94,7 +94,7 @@
 		pointsDict["Blue"] = 150; // Add "Blue" as a key and assign 150 as its value.
 		[/csharp]
 		[/codeblocks]
-		Finally, dictionaries can contain different types of keys and values in the same dictionary:
+		Finally, untyped dictionaries can contain different types of keys and values in the same dictionary:
 		[codeblocks]
 		[gdscript]
 		# This is a valid dictionary.
@@ -133,6 +133,39 @@
 		}
 		[/csharp]
 		[/codeblocks]
+		To enforce a certain type for keys and values, you can create a [i]typed dictionary[/i]. Typed dictionaries can only contain keys and values of the given types, or that inherit from the given classes:
+		[codeblocks]
+		[gdscript]
+		# Creates a typed dictionary with String keys and int values.
+		# Attempting to use any other type for keys or values will result in an error.
+		var typed_dict: Dictionary[String, int] = {
+			"some_key": 1,
+			"some_other_key": 2,
+		}
+
+		# Creates a typed dictionary with String keys and values of any type.
+		# Attempting to use any other type for keys will result in an error.
+		var typed_dict_key_only: Dictionary[String, Variant] = {
+			"some_key": 12.34,
+			"some_other_key": "string",
+		}
+		[/gdscript]
+		[csharp]
+		// Creates a typed dictionary with String keys and int values.
+		// Attempting to use any other type for keys or values will result in an error.
+		var typedDict = new Godot.Collections.Dictionary&lt;String, int&gt; {
+			{"some_key", 1},
+			{"some_other_key", 2},
+		};
+
+		// Creates a typed dictionary with String keys and values of any type.
+		// Attempting to use any other type for keys will result in an error.
+		var typedDictKeyOnly = new Godot.Collections.Dictionary&lt;String, Variant&gt; {
+			{"some_key", 12.34},
+			{"some_other_key", "string"},
+		};
+		[/csharp]
+		[/codeblocks]
 		[b]Note:[/b] Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use [method duplicate].
 		[b]Note:[/b] Erasing elements while iterating over dictionaries is [b]not[/b] supported and will result in unpredictable behavior.
 	</description>