Improve the Dictionary class documentation

- Mention Lua-style syntax.
- Make the code samples self-contained.
- Mention caveat with `const` (also in Array).
- Clarify the description of `size()`.

This closes https://github.com/godotengine/godot-docs/issues/4272.

2 files changed, 47 insertions, 34 deletions

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 0ad5960d4a..6a9eb89602 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -38,8 +38,9 @@
 		GD.Print(array1 + array2); // Prints [One, 2, 3, Four]
 		[/csharp]
 		[/codeblocks]
-		Note that concatenating with [code]+=[/code] operator will create a new array. If you want to append another array to an existing array, [method append_array] is more efficient.
+		[b]Note:[/b] Concatenating with the [code]+=[/code] operator will create a new array, which has a cost. If you want to append another array to an existing array, [method append_array] is more efficient.
 		[b]Note:[/b] Arrays are always passed by reference. To get a copy of an array which can be modified independently of the original array, use [method duplicate].
+		[b]Note:[/b] When declaring an array with [code]const[/code], the array itself can still be mutated by defining the values at individual indices or pushing/removing elements. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml
index dc38fdf0e8..cd0b5ac027 100644
--- a/doc/classes/Dictionary.xml
+++ b/doc/classes/Dictionary.xml
@@ -11,17 +11,28 @@
 		Creating a dictionary:
 		[codeblocks]
 		[gdscript]
-		var my_dir = {} # Creates an empty dictionary.
-		var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
-		var another_dir = {
-		    key1: value1,
-		    key2: value2,
-		    key3: value3,
+		var my_dict = {} # Creates an empty dictionary.
+
+		var dict_variable_key = "Another key name"
+		var dict_variable_value = "value2"
+		var another_dict = {
+		    "Some key name": "value1",
+		    dict_variable_key: dict_variable_value,
+		}
+
+		var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
+
+		# Alternative Lua-style syntax.
+		# Doesn't require quotes around keys, but only string constants can be used as key names.
+		# Additionally, key names must start with a letter or an underscore.
+		# Here, `some_key` is a string literal, not a variable!
+		another_dict = {
+		    some_key = 42,
 		}
 		[/gdscript]
 		[csharp]
-		var myDir = new Godot.Collections.Dictionary(); // Creates an empty dictionary.
-		var pointsDir = new Godot.Collections.Dictionary
+		var myDict = new Godot.Collections.Dictionary(); // Creates an empty dictionary.
+		var pointsDict = new Godot.Collections.Dictionary
 		{
 		    {"White", 50},
 		    {"Yellow", 75},
@@ -33,15 +44,15 @@
 		[codeblocks]
 		[gdscript]
 		export(string, "White", "Yellow", "Orange") var my_color
-		var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
+		var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
 		func _ready():
 		    # We can't use dot syntax here as `my_color` is a variable.
-		    var points = points_dir[my_color]
+		    var points = points_dict[my_color]
 		[/gdscript]
 		[csharp]
 		[Export(PropertyHint.Enum, "White,Yellow,Orange")]
 		public string MyColor { get; set; }
-		public Godot.Collections.Dictionary pointsDir = new Godot.Collections.Dictionary
+		public Godot.Collections.Dictionary pointsDict = new Godot.Collections.Dictionary
 		{
 		    {"White", 50},
 		    {"Yellow", 75},
@@ -50,7 +61,7 @@
 
 		public override void _Ready()
 		{
-		    int points = (int)pointsDir[MyColor];
+		    int points = (int)pointsDict[MyColor];
 		}
 		[/csharp]
 		[/codeblocks]
@@ -58,7 +69,7 @@
 		Dictionaries can contain more complex data:
 		[codeblocks]
 		[gdscript]
-		my_dir = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key.
+		my_dict = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key.
 		[/gdscript]
 		[csharp]
 		var myDir = new Godot.Collections.Dictionary
@@ -70,8 +81,8 @@
 		To add a key to an existing dictionary, access it like an existing key and assign to it:
 		[codeblocks]
 		[gdscript]
-		var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
-		points_dir["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.
+		var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
+		points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.
 		[/gdscript]
 		[csharp]
 		var pointsDir = new Godot.Collections.Dictionary
@@ -80,7 +91,7 @@
 		    {"Yellow", 75},
 		    {"Orange", 100}
 		};
-		pointsDir["blue"] = 150; // Add "Blue" as a key and assign 150 as its value.
+		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:
@@ -89,22 +100,22 @@
 		# This is a valid dictionary.
 		# To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`.
 		# Indexing styles can be mixed and matched depending on your needs.
-		var my_dir = {
+		var my_dict = {
 		    "String Key": 5,
 		    4: [1, 2, 3],
 		    7: "Hello",
-		    "sub_dir": {"sub_key": "Nested value"},
+		    "sub_dict": {"sub_key": "Nested value"},
 		}
 		[/gdscript]
 		[csharp]
 		// This is a valid dictionary.
 		// To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`.
 		// Indexing styles can be mixed and matched depending on your needs.
-		var myDir = new Godot.Collections.Dictionary {
+		var myDict = new Godot.Collections.Dictionary {
 		    {"String Key", 5},
 		    {4, new Godot.Collections.Array{1,2,3}},
 		    {7, "Hello"},
-		    {"sub_dir", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}}
+		    {"sub_dict", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}}
 		};
 		[/csharp]
 		[/codeblocks]
@@ -117,11 +128,11 @@
 		func compare_arrays():
 		    print(array1 == array2) # Will print true.
 
-		var dir1 = {"a": 1, "b": 2, "c": 3}
-		var dir2 = {"a": 1, "b": 2, "c": 3}
+		var dict1 = {"a": 1, "b": 2, "c": 3}
+		var dict2 = {"a": 1, "b": 2, "c": 3}
 
 		func compare_dictionaries():
-		    print(dir1 == dir2) # Will NOT print true.
+		    print(dict1 == dict2) # Will NOT print true.
 		[/gdscript]
 		[csharp]
 		// You have to use GD.Hash().
@@ -135,35 +146,36 @@
 		    GD.Print(GD.Hash(array1) == GD.Hash(array2)); // Will print true.
 		}
 
-		public Godot.Collections.Dictionary dir1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
-		public Godot.Collections.Dictionary dir2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
+		public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
+		public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
 
 		public void CompareDictionaries()
 		{
-		    GD.Print(dir1 == dir2); // Will NOT print true.
+		    GD.Print(dict1 == dict2); // Will NOT print true.
 		}
 		[/csharp]
 		[/codeblocks]
 		You need to first calculate the dictionary's hash with [method hash] before you can compare them:
 		[codeblocks]
 		[gdscript]
-		var dir1 = {"a": 1, "b": 2, "c": 3}
-		var dir2 = {"a": 1, "b": 2, "c": 3}
+		var dict1 = {"a": 1, "b": 2, "c": 3}
+		var dict2 = {"a": 1, "b": 2, "c": 3}
 
 		func compare_dictionaries():
-		    print(dir1.hash() == dir2.hash()) # Will print true.
+		    print(dict1.hash() == dict2.hash()) # Will print true.
 		[/gdscript]
 		[csharp]
 		// You have to use GD.Hash().
-		public Godot.Collections.Dictionary dir1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
-		public Godot.Collections.Dictionary dir2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
+		public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
+		public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
 
 		public void CompareDictionaries()
 		{
-		    GD.Print(GD.Hash(dir1) == GD.Hash(dir2)); // Will print true.
+		    GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Will print true.
 		}
 		[/csharp]
 		[/codeblocks]
+		[b]Note:[/b] When declaring a dictionary with [code]const[/code], the dictionary itself can still be mutated by defining the values of individual keys. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized.
 	</description>
 	<tutorials>
 		<link title="GDScript basics: Dictionary">https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_basics.html#dictionary</link>
@@ -322,7 +334,7 @@
 			<return type="int">
 			</return>
 			<description>
-				Returns the size of the dictionary (in pairs).
+				Returns the number of keys in the dictionary.
 			</description>
 		</method>
 		<method name="values">