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

---
 doc/classes/Array.xml      | 4 ++--
 doc/classes/Callable.xml   | 3 ++-
 doc/classes/Dictionary.xml | 3 ++-
 doc/classes/String.xml     | 3 ++-
 4 files changed, 8 insertions(+), 5 deletions(-)

(limited to 'doc/classes')

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 57f51c7ccf..a7de570a5e 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -299,8 +299,8 @@
 		<method name="hash" qualifiers="const">
 			<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/Callable.xml b/doc/classes/Callable.xml
index 2d3571e36c..f319f338ed 100644
--- a/doc/classes/Callable.xml
+++ b/doc/classes/Callable.xml
@@ -98,7 +98,8 @@
 		<method name="hash" qualifiers="const">
 			<return type="int" />
 			<description>
-				Returns the hash value of this [Callable]'s object.
+				Returns the 32-bit hash value of this [Callable]'s object.
+				[b]Note:[/b] [Callable]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 callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for [method hash].
 			</description>
 		</method>
 		<method name="is_custom" qualifiers="const">
diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml
index 7218e3bcb0..74942dc829 100644
--- a/doc/classes/Dictionary.xml
+++ b/doc/classes/Dictionary.xml
@@ -259,7 +259,7 @@
 		<method name="hash" qualifiers="const">
 			<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:
 				[codeblocks]
 				[gdscript]
 				var dict1 = {0: 10}
@@ -276,6 +276,7 @@
 				[/csharp]
 				[/codeblocks]
 				[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="is_empty" qualifiers="const">
diff --git a/doc/classes/String.xml b/doc/classes/String.xml
index a6182f5dab..6b8c455203 100644
--- a/doc/classes/String.xml
+++ b/doc/classes/String.xml
@@ -241,7 +241,8 @@
 		<method name="hash" qualifiers="const">
 			<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" qualifiers="const">
-- 
cgit v1.2.3