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 = 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 = HashMap::default(); +/// assert!(map.is_empty()); +/// # } +/// ``` +/// +/// [aHash]: https://github.com/tkaitchuck/aHash pub type HashMap = std::collections::HashMap; pub trait AHashExt { @@ -88,10 +121,43 @@ impl AHashExt for StableHashMap { } } -/// 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 = 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 = HashSet::default(); +/// assert!(map.is_empty()); +/// # } +/// ``` +/// +/// [aHash]: https://github.com/tkaitchuck/aHash pub type HashSet = std::collections::HashSet; impl AHashExt for HashSet {