From e5158ed96c4a14ef5f891efd8666783ae2c9fdc8 Mon Sep 17 00:00:00 2001
From: krunchington <krunchington@gmail.com>
Date: Mon, 17 Mar 2025 16:25:52 -0700
Subject: [PATCH] Update docs to explain default Hasher issue (#18350)

# Objective

I experienced an issue where `HashMap::new` was not returning a value
typed appropriately for a `HashMap<K,V>` declaration that omitted the
Hasher- e.g. the Default Hasher for the type is different than what the
`new` method produces.

After discussion on discord, this appears to be an issue in `hashbrown`,
and working around it would be very nontrivial, requiring a newtype on
top of the `hashbrown` implementation. Rather than doing that, it was
suggested that we add docs to make the issue more visible and provide a
clear workaround.

## Solution

Updated the docs for `bevy_platform_support::collections`. I couldn't
update Struct docs because they're re-exports, so I had to settle for
the module.

Note that the `[HashMap::new]` link wasn't generating properly- I'm not
sure why. I see the method in the docs.rs site,
https://docs.rs/hashbrown/0.15.1/hashbrown/struct.HashMap.html#method.new,
but not on the generated internal documentation. I wonder if `hashbrown`
isn't actually implementing the new or something?

## Testing

n/a although I did generate and open the docs on my Ubuntu machine.

---

## Showcase

before:

![image](https://github.com/user-attachments/assets/5c80417d-9c4e-4b57-825f-911203ed8558)

after:

![image](https://github.com/user-attachments/assets/420f6775-2f32-466f-a580-bb1344016bda)

---------

Co-authored-by: Zachary Harrold <zac@harrold.com.au>
---
 crates/bevy_platform_support/Cargo.toml       |  3 +++
 .../bevy_platform_support/src/collections.rs  | 23 ++++++++++++++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_platform_support/Cargo.toml b/crates/bevy_platform_support/Cargo.toml
index 75883a697c..cf5a660c25 100644
--- a/crates/bevy_platform_support/Cargo.toml
+++ b/crates/bevy_platform_support/Cargo.toml
@@ -58,6 +58,9 @@ hashbrown = { version = "0.15.1", features = [
   "raw-entry",
 ], optional = true, default-features = false }
 
+[dev-dependencies]
+bevy_ecs = { path = "../bevy_ecs", version = "0.16.0-dev" }
+
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 web-time = { version = "1.1", default-features = false, optional = true }
 getrandom = { version = "0.2.0", default-features = false, optional = true, features = [
diff --git a/crates/bevy_platform_support/src/collections.rs b/crates/bevy_platform_support/src/collections.rs
index 8a7fef6116..e4f6a821f4 100644
--- a/crates/bevy_platform_support/src/collections.rs
+++ b/crates/bevy_platform_support/src/collections.rs
@@ -1,6 +1,27 @@
-//! Provides [`HashMap`] and [`HashSet`] from [`hashbrown`] with some customized defaults.\
+//! Provides [`HashMap`] and [`HashSet`] from [`hashbrown`] with some customized defaults.
 //!
 //! Also provides the [`HashTable`] type, which is specific to [`hashbrown`].
+//!
+//! Note that due to the implementation details of [`hashbrown`], [`HashMap::new`] is only implemented for `HashMap<K, V, RandomState>`.
+//! Whereas, Bevy exports `HashMap<K, V, FixedHasher>` as its default [`HashMap`] type, meaning [`HashMap::new`] will typically fail.
+//! To bypass this issue, use [`HashMap::default`] instead.
+//!
+//! ```
+//! # use bevy_ecs::component::Component;
+//! # use bevy_ecs::system::Commands;
+//! # use bevy_platform_support::collections::HashMap;
+//!
+//! #[derive(Component)]
+//! struct MyComponent {
+//!     map: HashMap<String, String>
+//! }
+//!
+//! fn my_system(mut commands: Commands) {
+//!     commands.spawn(MyComponent {
+//!         map: HashMap::default(),
+//!     });
+//! }
+//! ```
 
 pub use hash_map::HashMap;
 pub use hash_set::HashSet;