Auto merge of #55012 - kennytm:rollup, r=kennytm

Rollup of 16 pull requests

Successful merges:

 - #54755 (Documents reference equality by address (#54197))
 - #54811 (During rustc bootstrap, make default for `optimize` independent of `debug`)
 - #54825 (NLL says "borrowed content" instead of more precise "dereference of raw pointer")
 - #54860 (Add doc comments about safest way to initialize a vector of zeros)
 - #54869 (Fix mobile docs)
 - #54891 (Fix tracking issue for Once::is_completed)
 - #54913 (doc fix: it's auto traits that make for automatic implementations)
 - #54920 (Fix handling of #[must_use] on unit and uninhabited types)
 - #54932 (A handful of random string-related improvements)
 - #54936 (impl Eq+Hash for TyLayout)
 - #54950 (std: Synchronize global allocator on wasm32)
 - #54956 ("(using ..." doesn't have the matching ")")
 - #54958 (add a macro for static (compile-time) assertions)
 - #54967 (Remove incorrect span for second label inner macro invocation)
 - #54983 (Fix slice's benchmarks)
 - #54989 (Fix spelling in the documentation to htmldocck.py)

Failed merges:

r? @ghost

2 files changed, 20 insertions, 11 deletions

diff --git a/src/liballoc/benches/slice.rs b/src/liballoc/benches/slice.rs
index a699ff9c0a7..490320f57cb 100644
--- a/src/liballoc/benches/slice.rs
+++ b/src/liballoc/benches/slice.rs
@@ -13,6 +13,7 @@ use std::mem;
 use std::ptr;
 
 use rand::{Rng, SeedableRng, XorShiftRng};
+use rand::distributions::{Standard, Alphanumeric};
 use test::{Bencher, black_box};
 
 #[bench]
@@ -192,18 +193,20 @@ fn gen_descending(len: usize) -> Vec<u64> {
     (0..len as u64).rev().collect()
 }
 
+const SEED: [u8; 16] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+
 fn gen_random(len: usize) -> Vec<u64> {
-    let mut rng = XorShiftRng::from_seed([0, 1, 2, 3]);
-    rng.gen_iter::<u64>().take(len).collect()
+    let mut rng = XorShiftRng::from_seed(SEED);
+    rng.sample_iter(&Standard).take(len).collect()
 }
 
 fn gen_random_bytes(len: usize) -> Vec<u8> {
-    let mut rng = XorShiftRng::from_seed([0, 1, 2, 3]);
-    rng.gen_iter::<u8>().take(len).collect()
+    let mut rng = XorShiftRng::from_seed(SEED);
+    rng.sample_iter(&Standard).take(len).collect()
 }
 
 fn gen_mostly_ascending(len: usize) -> Vec<u64> {
-    let mut rng = XorShiftRng::from_seed([0, 1, 2, 3]);
+    let mut rng = XorShiftRng::from_seed(SEED);
     let mut v = gen_ascending(len);
     for _ in (0usize..).take_while(|x| x * x <= len) {
         let x = rng.gen::<usize>() % len;
@@ -214,7 +217,7 @@ fn gen_mostly_ascending(len: usize) -> Vec<u64> {
 }
 
 fn gen_mostly_descending(len: usize) -> Vec<u64> {
-    let mut rng = XorShiftRng::from_seed([0, 1, 2, 3]);
+    let mut rng = XorShiftRng::from_seed(SEED);
     let mut v = gen_descending(len);
     for _ in (0usize..).take_while(|x| x * x <= len) {
         let x = rng.gen::<usize>() % len;
@@ -225,18 +228,18 @@ fn gen_mostly_descending(len: usize) -> Vec<u64> {
 }
 
 fn gen_strings(len: usize) -> Vec<String> {
-    let mut rng = XorShiftRng::from_seed([0, 1, 2, 3]);
+    let mut rng = XorShiftRng::from_seed(SEED);
     let mut v = vec![];
     for _ in 0..len {
         let n = rng.gen::<usize>() % 20 + 1;
-        v.push(rng.gen_ascii_chars().take(n).collect());
+        v.push(rng.sample_iter(&Alphanumeric).take(n).collect());
     }
     v
 }
 
 fn gen_big_random(len: usize) -> Vec<[u64; 16]> {
-    let mut rng = XorShiftRng::from_seed([0, 1, 2, 3]);
-    rng.gen_iter().map(|x| [x; 16]).take(len).collect()
+    let mut rng = XorShiftRng::from_seed(SEED);
+    rng.sample_iter(&Standard).map(|x| [x; 16]).take(len).collect()
 }
 
 macro_rules! sort {
diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs
index 2bc037e3fee..f7a0bbdceaf 100644
--- a/src/liballoc/vec.rs
+++ b/src/liballoc/vec.rs
@@ -120,11 +120,17 @@ use raw_vec::RawVec;
 /// assert_eq!(vec, [1, 2, 3, 4]);
 /// ```
 ///
-/// It can also initialize each element of a `Vec<T>` with a given value:
+/// It can also initialize each element of a `Vec<T>` with a given value.
+/// This may be more efficient than performing allocation and initialization
+/// in separate steps, especially when initializing a vector of zeros:
 ///
 /// ```
 /// let vec = vec![0; 5];
 /// assert_eq!(vec, [0, 0, 0, 0, 0]);
+///
+/// // The following is equivalent, but potentially slower:
+/// let mut vec1 = Vec::with_capacity(5);
+/// vec1.resize(5, 0);
 /// ```
 ///
 /// Use a `Vec<T>` as an efficient stack: