From f4cfcc0e44b91446beb49a1dbe9965cb7bcde059 Mon Sep 17 00:00:00 2001
From: dataphract <dataphract@gmail.com>
Date: Sat, 6 Nov 2021 20:53:12 +0000
Subject: [PATCH] explain absence of `new` constructor in Hash{Map, Set} docs;
 suggest `default` (#3077)

# Objective

Fixes #2823.

## Solution

This PR adds notes to the `HashMap` and `HashSet` docs explaining why `HashMap::new()` (resp. `HashSet::new()`) is not available, and guiding the user toward using the `Default` implementation for an empty collection.
---
 crates/bevy_utils/src/lib.rs | 74 ++++++++++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_utils/src/lib.rs b/crates/bevy_utils/src/lib.rs
index b76e0aebfa..4b810f0a21 100644
--- a/crates/bevy_utils/src/lib.rs
+++ b/crates/bevy_utils/src/lib.rs
@@ -31,10 +31,43 @@ impl std::hash::BuildHasher for FixedState {
     }
 }
 
-/// A std hash map implementing AHash, a high speed keyed hashing algorithm
-/// intended for use in in-memory hashmaps.
+/// A [`HashMap`][std::collections::HashMap] implementing [aHash][aHash], a high
+/// speed keyed hashing algorithm intended for use in in-memory hashmaps.
 ///
 /// AHash is designed for performance and is NOT cryptographically secure.
+///
+/// # Construction
+///
+/// Users may be surprised when a `HashMap` cannot be constructed with `HashMap::new()`:
+///
+/// ```compile_fail
+/// # fn main() {
+/// use bevy_utils::HashMap;
+///
+/// // Produces an error like "no function or associated item named `new` found [...]"
+/// let map: HashMap<String, String> = HashMap::new();
+/// # }
+/// ```
+///
+/// The standard library's [`HashMap::new`][std::collections::HashMap::new] is
+/// implemented only for `HashMap`s which use the
+/// [`DefaultHasher`][std::collections::hash_map::DefaultHasher], so it's not
+/// available for Bevy's `HashMap`.
+///
+/// However, an empty `HashMap` can easily be constructed using the `Default`
+/// implementation:
+///
+/// ```
+/// # fn main() {
+/// use bevy_utils::HashMap;
+///
+/// // This works!
+/// let map: HashMap<String, String> = HashMap::default();
+/// assert!(map.is_empty());
+/// # }
+/// ```
+///
+/// [aHash]: https://github.com/tkaitchuck/aHash
 pub type HashMap<K, V> = std::collections::HashMap<K, V, RandomState>;
 
 pub trait AHashExt {
@@ -88,10 +121,43 @@ impl<K, V> AHashExt for StableHashMap<K, V> {
     }
 }
 
-/// A std hash set implementing AHash, a high speed keyed hashing algorithm
-/// intended for use in in-memory hashmaps.
+/// A [`HashSet`][std::collections::HashSet] implementing [aHash][aHash], a high
+/// speed keyed hashing algorithm intended for use in in-memory hashmaps.
 ///
 /// AHash is designed for performance and is NOT cryptographically secure.
+///
+/// # Construction
+///
+/// Users may be surprised when a `HashSet` cannot be constructed with `HashSet::new()`:
+///
+/// ```compile_fail
+/// # fn main() {
+/// use bevy_utils::HashSet;
+///
+/// // Produces an error like "no function or associated item named `new` found [...]"
+/// let map: HashSet<String> = HashSet::new();
+/// # }
+/// ```
+///
+/// The standard library's [`HashSet::new`][std::collections::HashSet::new] is
+/// implemented only for `HashSet`s which use the
+/// [`DefaultHasher`][std::collections::hash_map::DefaultHasher], so it's not
+/// available for Bevy's `HashSet`.
+///
+/// However, an empty `HashSet` can easily be constructed using the `Default`
+/// implementation:
+///
+/// ```
+/// # fn main() {
+/// use bevy_utils::HashSet;
+///
+/// // This works!
+/// let map: HashSet<String> = HashSet::default();
+/// assert!(map.is_empty());
+/// # }
+/// ```
+///
+/// [aHash]: https://github.com/tkaitchuck/aHash
 pub type HashSet<K> = std::collections::HashSet<K, RandomState>;
 
 impl<K> AHashExt for HashSet<K> {