docs: update the documentation to fit all hash_map possibilities

Author: stifskere

library/std/src/macros.rs

@@ -394,14 +394,18 @@ macro_rules! repetition_utils {
 
 /// Creates a [`HashMap`] containing the arguments.
 ///
-/// This macro creates or either an empty [`HashMap`] using
-/// [`HashMap::new`] if there are no arguments, or generates
-/// a [`HashMap::insert`] call for each element.
+/// [`hash_map!`] allows specifying the entries that make
+/// up the [`HashMap`] where the key and value are separated by a `=>`.
 ///
-/// This macro allows trailing commas.
+/// The entries are separated by commas, where a trailing comma can be used
+/// for purposes like macro generation as well as many other things...
 ///
-/// This macro is used by concatenating comma separated sequences
-/// of `<key:expr> => <value:expr>`.
+/// It is semantically equivalent to using repeated [`HashMap::insert`]
+/// on a newly created hashmap. On the other hand, calling [`hash_map!`]
+/// without any argument is equivalent to invoking [`HashMap::new`].
+///
+/// A non empty [`hash_map!`] invocation calls [`HashMap::with_capacity`] and evaluates
+/// the argument size constantly passing it to the function itself.
 ///
 /// # Examples
 ///
@@ -415,9 +419,10 @@ macro_rules! repetition_utils {
 ///
 /// assert_eq!(map.get("key"), Some(&"value"));
 /// assert_eq!(map.get("key1"), Some(&"value1"));
+/// assert!(map.get("brrrrrrooooommm").is_none());
 /// ```
 ///
-/// This macro also supports trailing comma.
+/// And with a trailing comma
 ///
 ///```rust
 /// #![feature(hash_map_macro)]
@@ -434,6 +439,7 @@ macro_rules! repetition_utils {
 /// [`HashMap`]: crate::collections::HashMap
 /// [`HashMap::new`]: crate::collections::HashMap::new
 /// [`HashMap::insert`]: crate::collections::HashMap::insert
+/// [`HashMap::with_capacity`]: crate::collections::HashMap::with_capacity
 #[macro_export]
 #[allow_internal_unstable(hash_map_internals)]
 #[unstable(feature = "hash_map_macro", issue = "144032")]