Merge pull request #59637 from Calinou/doc-poolarray-value-caveats

doc/classes/PoolByteArray.xml

@@ -5,7 +5,20 @@
 	</brief_description>
 	<description>
 		An array specifically designed to hold bytes. Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolByteArray] or mutating a [PoolByteArray] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolByteArray()]
+		array[0].push_back(123)
+		print(array)  # [[]] (empty PoolByteArray within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolByteArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolByteArray()]
+		var pool_array = array[0]
+		pool_array.push_back(123)
+		array[0] = pool_array
+		print(array)  # [[123]] (PoolByteArray with 1 element inside an Array)
+		[/codeblock]
 	</description>
 	<tutorials>
 	</tutorials>

doc/classes/PoolColorArray.xml

@@ -1,11 +1,24 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PoolColorArray" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		A pooled array of [Color].
+		A pooled array of [Color]s.
 	</brief_description>
 	<description>
 		An array specifically designed to hold [Color]. Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolColorArray] or mutating a [PoolColorArray] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolColorArray()]
+		array[0].push_back(Color(0.1, 0.2, 0.3, 0.4))
+		print(array)  # [[]] (empty PoolColorArray within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolColorArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolColorArray()]
+		var pool_array = array[0]
+		pool_array.push_back(Color(0.1, 0.2, 0.3, 0.4))
+		array[0] = pool_array
+		print(array)  # [[(0.1, 0.2, 0.3, 0.4)]] (PoolColorArray with 1 element inside an Array)
+		[/codeblock]
 	</description>
 	<tutorials>
 	</tutorials>

doc/classes/PoolIntArray.xml

@@ -5,7 +5,20 @@
 	</brief_description>
 	<description>
 		An array specifically designed to hold integer values ([int]). Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolIntArray] or mutating a [PoolIntArray] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolIntArray()]
+		array[0].push_back(1234)
+		print(array)  # [[]] (empty PoolIntArray within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolIntArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolIntArray()]
+		var pool_array = array[0]
+		pool_array.push_back(1234)
+		array[0] = pool_array
+		print(array)  # [[1234]] (PoolIntArray with 1 element inside an Array)
+		[/codeblock]
 		[b]Note:[/b] This type is limited to signed 32-bit integers, which means it can only take values in the interval [code][-2^31, 2^31 - 1][/code], i.e. [code][-2147483648, 2147483647][/code]. Exceeding those bounds will wrap around. In comparison, [int] uses signed 64-bit integers which can hold much larger values.
 	</description>
 	<tutorials>

doc/classes/PoolRealArray.xml

@@ -1,11 +1,24 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PoolRealArray" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		A pooled array of reals ([float]).
+		A pooled array of real numbers ([float]).
 	</brief_description>
 	<description>
 		An array specifically designed to hold floating-point values. Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolRealArray] or mutating a [PoolRealArray] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolRealArray()]
+		array[0].push_back(12.34)
+		print(array)  # [[]] (empty PoolRealArray within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolRealArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolRealArray()]
+		var pool_array = array[0]
+		pool_array.push_back(12.34)
+		array[0] = pool_array
+		print(array)  # [[12.34]] (PoolRealArray with 1 element inside an Array)
+		[/codeblock]
 		[b]Note:[/b] Unlike primitive [float]s which are 64-bit, numbers stored in [PoolRealArray] are 32-bit floats. This means values stored in [PoolRealArray] have lower precision compared to primitive [float]s. If you need to store 64-bit floats in an array, use a generic [Array] with [float] elements as these will still be 64-bit. However, using a generic [Array] to store [float]s will use roughly 6 times more memory compared to a [PoolRealArray].
 	</description>
 	<tutorials>

doc/classes/PoolStringArray.xml

@@ -1,11 +1,24 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PoolStringArray" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		A pooled array of [String].
+		A pooled array of [String]s.
 	</brief_description>
 	<description>
 		An array specifically designed to hold [String]s. Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolStringArray] or mutating a [PoolStringArray] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolStringArray()]
+		array[0].push_back("hello")
+		print(array)  # [[]] (empty PoolStringArray within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolStringArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolStringArray()]
+		var pool_array = array[0]
+		pool_array.push_back("hello")
+		array[0] = pool_array
+		print(array)  # [[hello]] (PoolStringArray with 1 element inside an Array)
+		[/codeblock]
 	</description>
 	<tutorials>
 		<link title="OS Test Demo">https://godotengine.org/asset-library/asset/677</link>

doc/classes/PoolVector2Array.xml

@@ -1,11 +1,24 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PoolVector2Array" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		A pooled array of [Vector2].
+		A pooled array of [Vector2]s.
 	</brief_description>
 	<description>
 		An array specifically designed to hold [Vector2]. Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolVector2Array] or mutating a [PoolVector2Array] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolVector2Array()]
+		array[0].push_back(Vector2(12, 34))
+		print(array)  # [[]] (empty PoolVector2Array within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolVector2Array] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolVector2Array()]
+		var pool_array = array[0]
+		pool_array.push_back(Vector2(12, 34))
+		array[0] = pool_array
+		print(array)  # [[(12, 34)]] (PoolVector2Array with 1 element inside an Array)
+		[/codeblock]
 	</description>
 	<tutorials>
 		<link title="2D Navigation Astar Demo">https://godotengine.org/asset-library/asset/519</link>

doc/classes/PoolVector3Array.xml

@@ -5,7 +5,20 @@
 	</brief_description>
 	<description>
 		An array specifically designed to hold [Vector3]. Optimized for memory usage, does not fragment the memory.
-		[b]Note:[/b] This type is passed by value and not by reference.
+		[b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolVector3Array] or mutating a [PoolVector3Array] within an [Array] or [Dictionary], changes will be lost:
+		[codeblock]
+		var array = [PoolVector3Array()]
+		array[0].push_back(Vector3(12, 34, 56))
+		print(array)  # [[]] (empty PoolVector3Array within an empty Array)
+		[/codeblock]
+		Instead, the entire [PoolVector3Array] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
+		[codeblock]
+		var array = [PoolVector3Array()]
+		var pool_array = array[0]
+		pool_array.push_back(Vector3(12, 34, 56))
+		array[0] = pool_array
+		print(array)  # [[(12, 34, 56)]] (PoolVector3Array with 1 element inside an Array)
+		[/codeblock]
 	</description>
 	<tutorials>
 	</tutorials>