docs: re-write documentation for better looks

Author: stifskere

library/std/src/macros.rs

@@ -397,14 +397,15 @@ macro_rules! repetition_utils {
 /// [`hash_map!`] allows specifying the entries that make
 /// up the [`HashMap`] where the key and value are separated by a `=>`.
 ///
-/// The entries are separated by commas, where a trailing comma can be used
-/// for purposes like macro generation as well as many other things...
+/// The entries are separated by commas with a trailing comma being allowed.
 ///
 /// 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`].
+/// on a newly created hashmap.
 ///
-/// A non empty [`hash_map!`] invocation calls [`HashMap::with_capacity`] and evaluates
+/// [`hash_map!`] will attempt to avoid repeated reallocations by
+/// using [`HashMap::with_capacity`].
+///
+/// A non-empty [`hash_map!`] invocation calls [`HashMap::with_capacity`] and evaluates
 /// the argument size constantly passing it to the function itself.
 ///
 /// # Examples