From 09599bc16429c87fbf9428b6613b51d6f3c58ab8 Mon Sep 17 00:00:00 2001
From: Diggory Hardy <git@dhardy.name>
Date: Thu, 15 Mar 2018 12:18:42 +0000
Subject: [PATCH] Improve doc for NewRng::new alternative

---
 src/lib.rs | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 87fe888c0c5..1e5a081fb3e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -768,10 +768,25 @@ pub trait NewRng: SeedableRng {
     ///
     /// Normally this will use `OsRng`, but if that fails `JitterRng` will be
     /// used instead. Both should be suitable for cryptography. It is possible
-    /// that both entropy sources will fail though unlikely.
+    /// that both entropy sources will fail though unlikely; failures would
+    /// almost certainly be platform limitations or build issues, i.e. most
+    /// applications targetting PC/mobile platforms should not need to worry
+    /// about this failing.
     /// 
-    /// Panics on error. If error handling is desired, use
-    /// `RNG::from_rng(&mut EntropyRng::new())` instead.
+    /// If all entropy sources fail this will panic. If you need to handle
+    /// errors, use the following code, equivalent aside from error handling:
+    /// 
+    /// ```rust
+    /// use rand::{Rng, StdRng, EntropyRng, SeedableRng, Error};
+    /// 
+    /// fn foo() -> Result<(), Error> {
+    ///     // This uses StdRng, but is valid for any R: SeedableRng
+    ///     let mut rng = StdRng::from_rng(&mut EntropyRng::new())?;
+    ///     
+    ///     println!("random number: {}", rng.gen_range(1, 10));
+    ///     Ok(())
+    /// }
+    /// ```
     fn new() -> Self;
 }