From c8b8444ce131798b94e759138bb307144ed0994f Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Thu, 17 Jul 2014 11:59:45 -0400
Subject: [PATCH] Improve documentation for rand::random

This is now linked to in the guide, so I want to make sure it's good. This
adds a bit more explanation, and brings usage in line with current good style.
---
 src/libstd/rand/mod.rs | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/src/libstd/rand/mod.rs b/src/libstd/rand/mod.rs
index 0ffaadef0a130..a9b9a907a2642 100644
--- a/src/libstd/rand/mod.rs
+++ b/src/libstd/rand/mod.rs
@@ -226,19 +226,24 @@ impl Rng for TaskRng {
     }
 }
 
-/// Generate a random value using the task-local random number
-/// generator.
+/// Generates a random value using the task-local random number generator.
 ///
-/// # Example
+/// `random()` can generate various types of random things, and so may require
+/// type hinting to generate the specific type you want.
+///
+/// # Examples
 ///
 /// ```rust
-/// use std::rand::random;
+/// use std::rand;
+///
+/// let x = rand::random();
+/// println!("{}", 2u * x);
+///
+/// let y = rand::random::<f64>();
+/// println!("{}", y);
 ///
-/// if random() {
-///     let x = random();
-///     println!("{}", 2u * x);
-/// } else {
-///     println!("{}", random::<f64>());
+/// if rand::random() { // generates a boolean
+///     println!("Better lucky than good!");
 /// }
 /// ```
 #[inline]