hash_map: update doc comments for rehash()

lib/std/hash_map.zig

@@ -1509,7 +1509,16 @@ pub fn HashMapUnmanaged(
             return result;
         }
 
-        /// Rehash the map, in-place
+        /// Rehash the map, in-place.
+        ///
+        /// Over time, due to the current tombstone-based implementation, a
+        /// HashMap could become fragmented due to the buildup of tombstone
+        /// entries that causes a performance degradation due to excessive
+        /// probing. The kind of pattern that might cause this is a long-lived
+        /// HashMap with repeated inserts and deletes.
+        ///
+        /// All existing key/value pointers in the HashMap are maintained at
+        /// their new rehashed location.
         pub fn rehash(self: *Self, ctx: anytype) void {
             const mask = self.capacity() - 1;