From b215faa44f909c35fdd0e5f6daa6c32961b4ae8e Mon Sep 17 00:00:00 2001
From: Runxi Yu <me@runxiyu.org>
Date: Fri, 19 Sep 2025 14:21:25 +0800
Subject: [PATCH] Explain why fallback functions are necessary in hashmaps

---
 ds/map/hashmap/new.ha         | 8 ++++++++
 ds/map/hashmap_fnv/new.ha     | 8 ++++++++
 ds/map/hashmap_siphash/new.ha | 8 ++++++++

diff --git a/ds/map/hashmap/new.ha b/ds/map/hashmap/new.ha
index 17df04134be34b10b2e6169384fd762f5a512899..ab98752f5cc44f2673777deeba3254107ed810e5 100644
--- a/ds/map/hashmap/new.ha
+++ b/ds/map/hashmap/new.ha
@@ -8,6 +8,14 @@ use ds::map;
 
 // Creates a new [[map]] with a function that creates fallback maps, the number
 // of buckets, and the hash function and parameters.
+//
+// Hash collisions are virtually inevitable for typical map sizes. Therefore,
+// you are required to supply a function that helps creates fallback maps, which
+// are used to distinguish between items when they collide in hash.
+//
+// Alternatively, you may wish to use [[ds::map::swiss]] for Swiss Tables,
+// which do not require a custom fallback mechanism and are typically more
+// performant than hashmaps.
 export fn new(
 	make_fallback: *fn() (*map::map | nomem),
 	n: size,
diff --git a/ds/map/hashmap_fnv/new.ha b/ds/map/hashmap_fnv/new.ha
index 356bf4a585244da0cdb2f252888c98e5814012a0..f91e2a2cc7997c92bb06abcc4b102464298ec4f5 100644
--- a/ds/map/hashmap_fnv/new.ha
+++ b/ds/map/hashmap_fnv/new.ha
@@ -8,6 +8,14 @@ use ds::map::hashmap;
 
 // Creates a new [[map]] with the given number of buckets.
 // make_fallback is a function that creates per-bucket fallback maps.
+//
+// Hash collisions are virtually inevitable for typical map sizes. Therefore,
+// you are required to supply a function that helps creates fallback maps, which
+// are used to distinguish between items when they collide in hash.
+//
+// Alternatively, you may wish to use [[ds::map::swiss]] for Swiss Tables,
+// which do not require a custom fallback mechanism and are typically more
+// performant than hashmaps.
 export fn new(
 	make_fallback: *fn() (*map::map | nomem),
 	n: size,
diff --git a/ds/map/hashmap_siphash/new.ha b/ds/map/hashmap_siphash/new.ha
index d6392c7d9304076d201f0d87cb22142c51524e7b..7d2f1385a2d7a9e4516a558f27ebe5bd39d606da 100644
--- a/ds/map/hashmap_siphash/new.ha
+++ b/ds/map/hashmap_siphash/new.ha
@@ -8,6 +8,14 @@ use ds::map::hashmap;
 
 // Creates a new [[map]] with a function that creates fallback maps, the number
 // of buckets, and the SipHash key.
+//
+// Hash collisions are virtually inevitable for typical map sizes. Therefore,
+// you are required to supply a function that helps creates fallback maps, which
+// are used to distinguish between items when they collide in hash.
+//
+// Alternatively, you may wish to use [[ds::map::swiss]] for Swiss Tables,
+// which do not require a custom fallback mechanism and are typically more
+// performant than hashmaps.
 export fn new(
 	make_fallback: *fn() (*map::map | nomem),
 	n: size,

-- 
2.48.1