auto merge of #5825 : danluu/rust/rngdoc, r=erickt

This adds an example for most of the methods in Rng.

As a total newcomer to Rust, it took a while to figure out how to do basic things like use library functions, because there aren't many usage examples, and most examples that Google turns up are out of date. Something like this would have saved me a bit of time.

This might be a bit verbose. Some alternative options would be to consolidate all the examples into one section, or to only have code for the specific function call inline.

Author: bors

src/libcore/rand.rs

@@ -150,7 +150,21 @@ pub struct Weighted<T> {
 
 pub trait RngUtil {
     fn gen<T:Rand>(&self) -> T;
-    /// Return a random int
+    /**
+     * Return a random int
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%d",rng.gen_int()));
+     * }
+     * ~~~
+     */
     fn gen_int(&self) -> int;
     fn gen_int_range(&self, start: int, end: int) -> int;
     /// Return a random i8
@@ -176,7 +190,21 @@ pub trait RngUtil {
     fn gen_u32(&self) -> u32;
     /// Return a random u64
     fn gen_u64(&self) -> u64;
-    /// Return a random float in the interval [0,1]
+    /**
+     * Return random float in the interval [0,1]
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%f",rng.gen_float()));
+     * }
+     * ~~~
+     */
     fn gen_float(&self) -> float;
     /// Return a random f32 in the interval [0,1]
     fn gen_f32(&self) -> f32;
@@ -188,38 +216,184 @@ pub trait RngUtil {
      * Return a char randomly chosen from chars, failing if chars is empty
      */
     fn gen_char_from(&self, chars: &str) -> char;
-    /// Return a random bool
+    /**
+     * Return a random bool
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%b",rng.gen_bool()));
+     * }
+     * ~~~
+     */
     fn gen_bool(&self) -> bool;
-    /// Return a bool with a 1 in n chance of true
+    /**
+     * Return a bool with a 1 in n chance of true
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%b",rng.gen_weighted_bool(3)));
+     * }
+     * ~~~
+     */
     fn gen_weighted_bool(&self, n: uint) -> bool;
     /**
      * Return a random string of the specified length composed of A-Z,a-z,0-9
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(rng.gen_str(8));
+     * }
+     * ~~~
      */
     fn gen_str(&self, len: uint) -> ~str;
-    /// Return a random byte string of the specified length
+    /**
+     * Return a random byte string of the specified length
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%?",rng.gen_bytes(8)));
+     * }
+     * ~~~
+     */
     fn gen_bytes(&self, len: uint) -> ~[u8];
-    /// Choose an item randomly, failing if values is empty
+    ///
+    /**
+     * Choose an item randomly, failing if values is empty
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%d",rng.choose([1,2,4,8,16,32])));
+     * }
+     * ~~~
+     */
     fn choose<T:Copy>(&self, values: &[T]) -> T;
     /// Choose Some(item) randomly, returning None if values is empty
     fn choose_option<T:Copy>(&self, values: &[T]) -> Option<T>;
     /**
      * Choose an item respecting the relative weights, failing if the sum of
      * the weights is 0
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     let x = [rand::Weighted {weight: 4, item: 'a'},
+     *              rand::Weighted {weight: 2, item: 'b'},
+     *              rand::Weighted {weight: 2, item: 'c'}];
+     *     println(fmt!("%c",rng.choose_weighted(x)));
+     * }
+     * ~~~
      */
     fn choose_weighted<T:Copy>(&self, v : &[Weighted<T>]) -> T;
     /**
      * Choose Some(item) respecting the relative weights, returning none if
      * the sum of the weights is 0
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     let x = [rand::Weighted {weight: 4, item: 'a'},
+     *              rand::Weighted {weight: 2, item: 'b'},
+     *              rand::Weighted {weight: 2, item: 'c'}];
+     *     println(fmt!("%?",rng.choose_weighted_option(x)));
+     * }
+     * ~~~
      */
     fn choose_weighted_option<T:Copy>(&self, v: &[Weighted<T>]) -> Option<T>;
     /**
      * Return a vec containing copies of the items, in order, where
      * the weight of the item determines how many copies there are
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     let x = [rand::Weighted {weight: 4, item: 'a'},
+     *              rand::Weighted {weight: 2, item: 'b'},
+     *              rand::Weighted {weight: 2, item: 'c'}];
+     *     println(fmt!("%?",rng.weighted_vec(x)));
+     * }
+     * ~~~
      */
     fn weighted_vec<T:Copy>(&self, v: &[Weighted<T>]) -> ~[T];
-    /// Shuffle a vec
+    /**
+     * Shuffle a vec
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     println(fmt!("%?",rng.shuffle([1,2,3])));
+     * }
+     * ~~~
+     */
     fn shuffle<T:Copy>(&self, values: &[T]) -> ~[T];
-    /// Shuffle a mutable vec in place
+    /**
+     * Shuffle a mutable vec in place
+     *
+     * *Example*
+     *
+     * ~~~
+     *
+     * use core::rand::RngUtil;
+     *
+     * fn main() {
+     *     rng = rand::Rng();
+     *     let mut y = [1,2,3];
+     *     rng.shuffle_mut(y);
+     *     println(fmt!("%?",y));
+     *     rng.shuffle_mut(y);
+     *     println(fmt!("%?",y));
+     * }
+     * ~~~
+     */
     fn shuffle_mut<T>(&self, values: &mut [T]);
 }
 
@@ -337,7 +511,7 @@ impl RngUtil for @Rng {
         self.next() & 1u32 == 1u32
     }
 
-    /// Return a bool with a 1 in n chance of true
+    /// Return a bool with a 1-in-n chance of true
     fn gen_weighted_bool(&self, n: uint) -> bool {
         if n == 0u {
             true