From 5ca3a360d1a8ac657f9d8bd99c48d66e64e2bdb1 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Sat, 12 Feb 2022 22:17:35 +0100
Subject: [PATCH] Clarify identical `hash()` return values due to collisions

(cherry picked from commit 08541fe11d1e3945549f33a013b3d655413dcfa6)
---
 doc/classes/Array.xml      | 4 ++--
 doc/classes/Dictionary.xml | 3 ++-
 doc/classes/String.xml     | 3 ++-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 92c320e0a18..6839f1d8328 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -221,8 +221,8 @@
 		<method name="hash">
 			<return type="int" />
 			<description>
-				Returns a hashed integer value representing the array and its contents.
-				[b]Note:[/b] Arrays with equal contents can still produce different hashes. Only the exact same arrays will produce the same hashed integer value.
+				Returns a hashed 32-bit integer value representing the array and its contents.
+				[b]Note:[/b] [Array]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the arrays are equal, because different arrays can have identical hash values due to hash collisions.
 			</description>
 		</method>
 		<method name="insert">
diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml
index 6742bd2723b..b197e7c460f 100644
--- a/doc/classes/Dictionary.xml
+++ b/doc/classes/Dictionary.xml
@@ -147,7 +147,7 @@
 		<method name="hash">
 			<return type="int" />
 			<description>
-				Returns a hashed integer value representing the dictionary contents. This can be used to compare dictionaries by value:
+				Returns a hashed 32-bit integer value representing the dictionary contents. This can be used to compare dictionaries by value:
 				[codeblock]
 				var dict1 = {0: 10}
 				var dict2 = {0: 10}
@@ -155,6 +155,7 @@
 				print(dict1.hash() == dict2.hash())
 				[/codeblock]
 				[b]Note:[/b] Dictionaries with the same keys/values but in a different order will have a different hash.
+				[b]Note:[/b] Dictionaries with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the dictionaries are equal, because different dictionaries can have identical hash values due to hash collisions.
 			</description>
 		</method>
 		<method name="keys">
diff --git a/doc/classes/String.xml b/doc/classes/String.xml
index d3c3e0ad635..1e2dfacd4aa 100644
--- a/doc/classes/String.xml
+++ b/doc/classes/String.xml
@@ -351,7 +351,8 @@
 		<method name="hash">
 			<return type="int" />
 			<description>
-				Hashes the string and returns a 32-bit integer.
+				Returns the 32-bit hash value representing the string's contents.
+				[b]Note:[/b] [String]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the strings are equal, because different strings can have identical hash values due to hash collisions.
 			</description>
 		</method>
 		<method name="hex_to_int">