Better random chars example (take 2)

Cargo.toml

@@ -16,6 +16,15 @@ autobenches = true
 edition = "2018"
 include = ["src/", "LICENSE-*", "README.md", "CHANGELOG.md", "COPYRIGHT"]
 
+[package.metadata.docs.rs]
+# To build locally:
+# RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --all-features --no-deps --open
+all-features = true
+rustdoc-args = ["--cfg", "doc_cfg"]
+
+[package.metadata.playground]
+features = ["small_rng", "serde1"]
+
 [features]
 # Meta-features:
 default = ["std", "std_rng"]
@@ -74,12 +83,3 @@ libc = { version = "0.2.22", optional = true, default-features = false }
 rand_pcg = { path = "rand_pcg", version = "0.3.0" }
 # Only to test serde1
 bincode = "1.2.1"
-
-[package.metadata.docs.rs]
-# To build locally:
-# RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --all-features --no-deps --open
-all-features = true
-rustdoc-args = ["--cfg", "doc_cfg"]
-
-[package.metadata.playground]
-features = ["small_rng", "serde1"]

rand_core/Cargo.toml

@@ -14,15 +14,6 @@ keywords = ["random", "rng"]
 categories = ["algorithms", "no-std"]
 edition = "2018"
 
-[features]
-std = ["alloc", "getrandom", "getrandom/std"]    # use std library; should be default but for above bug
-alloc = []  # enables Vec and Box support without std
-serde1 = ["serde"] # enables serde for BlockRng wrapper
-
-[dependencies]
-serde = { version = "1", features = ["derive"], optional = true }
-getrandom = { version = "0.2", optional = true }
-
 [package.metadata.docs.rs]
 # To build locally:
 # RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --all-features --no-deps --open
@@ -31,3 +22,12 @@ rustdoc-args = ["--cfg", "doc_cfg"]
 
 [package.metadata.playground]
 all-features = true
+
+[features]
+std = ["alloc", "getrandom", "getrandom/std"]    # use std library; should be default but for above bug
+alloc = []  # enables Vec and Box support without std
+serde1 = ["serde"] # enables serde for BlockRng wrapper
+
+[dependencies]
+serde = { version = "1", features = ["derive"], optional = true }
+getrandom = { version = "0.2", optional = true }

src/distributions/other.rs

@@ -32,19 +32,22 @@ use std::mem::{self, MaybeUninit};
 /// # Example
 ///
 /// ```
-/// use std::iter;
 /// use rand::{Rng, thread_rng};
 /// use rand::distributions::Alphanumeric;
 ///
 /// let mut rng = thread_rng();
-/// let chars: String = iter::repeat(())
-///         .map(|()| rng.sample(Alphanumeric))
-///         .map(char::from)
-///         .take(7)
-///         .collect();
+/// let chars: String = (0..7).map(|_| rng.sample(Alphanumeric) as char).collect();
 /// println!("Random chars: {}", chars);
 /// ```
 ///
+/// The [`DistString`] trait provides an easier method of generating
+/// a random `String`, and offers more efficient allocation:
+/// ```
+/// use rand::distributions::{Alphanumeric, DistString};
+/// let string = Alphanumeric.sample_string(&mut rand::thread_rng(), 16);
+/// println!("Random string: {}", string);
+/// ```
+///
 /// # Passwords
 ///
 /// Users sometimes ask whether it is safe to use a string of random characters