[Merged by Bors] - explain absence of new constructor in Hash{Map, Set} docs; suggest default

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> {