auto merge of #11150 : huonw/rust/moar-docs, r=alexcrichton

(I removed the `fn main` from the `std::rand` examples to make it consistent with the rest of the codebase.)

Author: bors

src/libstd/hashmap.rs

@@ -12,6 +12,45 @@
 //!
 //! The tables use a keyed hash with new random keys generated for each container, so the ordering
 //! of a set of keys in a hash table is randomized.
+//!
+//! # Example
+//!
+//! ```rust
+//! use std::hashmap::HashMap;
+//!
+//! // type inference lets us omit an explicit type signature (which
+//! // would be `HashMap<&str, &str>` in this example).
+//! let mut book_reviews = HashMap::new();
+//!
+//! // review some books.
+//! book_reviews.insert("Adventures of Hucklebury Fin",      "My favorite book.");
+//! book_reviews.insert("Grimms' Fairy Tales",               "Masterpiece.");
+//! book_reviews.insert("Pride and Prejudice",               "Very enjoyable.");
+//! book_reviews.insert("The Adventures of Sherlock Holmes", "Eye lyked it alot.");
+//!
+//! // check for a specific one.
+//! if !book_reviews.contains_key(& &"Les Misérables") {
+//!     println!("We've got {} reviews, but Les Misérables ain't one.",
+//!              book_reviews.len());
+//! }
+//!
+//! // oops, this review has a lot of spelling mistakes, let's delete it.
+//! book_reviews.remove(& &"The Adventures of Sherlock Holmes");
+//!
+//! // look up the values associated with some keys.
+//! let to_find = ["Pride and Prejudice", "Alice's Adventure in Wonderland"];
+//! for book in to_find.iter() {
+//!     match book_reviews.find(book) {
+//!         Some(review) => println!("{}: {}", *book, *review),
+//!         None => println!("{} is unreviewed.", *book)
+//!     }
+//! }
+//!
+//! // iterate over everything.
+//! for (book, review) in book_reviews.iter() {
+//!     println!("{}: \"{}\"", *book, *review);
+//! }
+//! ```
 
 use container::{Container, Mutable, Map, MutableMap, Set, MutableSet};
 use clone::Clone;
@@ -354,6 +393,43 @@ impl<K: Hash + Eq, V> HashMap<K, V> {
 
     /// Modify and return the value corresponding to the key in the map, or
     /// insert and return a new value if it doesn't exist.
+    ///
+    /// This method allows for all insertion behaviours of a hashmap,
+    /// see methods like `insert`, `find_or_insert` and
+    /// `insert_or_update_with` for less general and more friendly
+    /// variations of this.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::hashmap::HashMap;
+    ///
+    /// // map some strings to vectors of strings
+    /// let mut map = HashMap::<~str, ~[~str]>::new();
+    /// map.insert(~"a key", ~[~"value"]);
+    /// map.insert(~"z key", ~[~"value"]);
+    ///
+    /// let new = ~[~"a key", ~"b key", ~"z key"];
+    /// for k in new.move_iter() {
+    ///     map.mangle(k, ~"new value",
+    ///                // if the key doesn't exist in the map yet, add it in
+    ///                // the obvious way.
+    ///                |_k, v| ~[v],
+    ///                // if the key does exist either prepend or append this
+    ///                // new value based on the first letter of the key.
+    ///                |key, already, new| {
+    ///                     if key.starts_with("z") {
+    ///                         already.unshift(new);
+    ///                     } else {
+    ///                         already.push(new);
+    ///                     }
+    ///                });
+    /// }
+    ///
+    /// for (k, v) in map.iter() {
+    ///    println!("{} -> {:?}", *k, *v);
+    /// }
+    /// ```
     pub fn mangle<'a,
                   A>(
                   &'a mut self,

src/libstd/rand/distributions/exponential.rs

@@ -60,11 +60,9 @@ impl Rand for Exp1 {
 /// use std::rand;
 /// use std::rand::distributions::{Exp, IndependentSample};
 ///
-/// fn main() {
-///     let exp = Exp::new(2.0);
-///     let v = exp.ind_sample(&mut rand::task_rng());
-///     println!("{} is from a Exp(2) distribution", v);
-/// }
+/// let exp = Exp::new(2.0);
+/// let v = exp.ind_sample(&mut rand::task_rng());
+/// println!("{} is from a Exp(2) distribution", v);
 /// ```
 pub struct Exp {
     /// `lambda` stored as `1/lambda`, since this is what we scale by.

src/libstd/rand/distributions/gamma.rs

@@ -37,11 +37,9 @@ use num;
 /// use std::rand;
 /// use std::rand::distributions::{IndependentSample, Gamma};
 ///
-/// fn main() {
-///     let gamma = Gamma::new(2.0, 5.0);
-///     let v = gamma.ind_sample(&mut rand::task_rng());
-///     println!("{} is from a Gamma(2, 5) distribution", v);
-/// }
+/// let gamma = Gamma::new(2.0, 5.0);
+/// let v = gamma.ind_sample(&mut rand::task_rng());
+/// println!("{} is from a Gamma(2, 5) distribution", v);
 /// ```
 ///
 /// [1]: George Marsaglia and Wai Wan Tsang. 2000. "A Simple Method
@@ -183,11 +181,9 @@ impl IndependentSample<f64> for GammaLargeShape {
 /// use std::rand;
 /// use std::rand::distributions::{ChiSquared, IndependentSample};
 ///
-/// fn main() {
-///     let chi = ChiSquared::new(11.0);
-///     let v = chi.ind_sample(&mut rand::task_rng());
-///     println!("{} is from a χ²(11) distribution", v)
-/// }
+/// let chi = ChiSquared::new(11.0);
+/// let v = chi.ind_sample(&mut rand::task_rng());
+/// println!("{} is from a χ²(11) distribution", v)
 /// ```
 pub enum ChiSquared {
     // k == 1, Gamma(alpha, ..) is particularly slow for alpha < 1,
@@ -237,11 +233,9 @@ impl IndependentSample<f64> for ChiSquared {
 /// use std::rand;
 /// use std::rand::distributions::{FisherF, IndependentSample};
 ///
-/// fn main() {
-///     let f = FisherF::new(2.0, 32.0);
-///     let v = f.ind_sample(&mut rand::task_rng());
-///     println!("{} is from an F(2, 32) distribution", v)
-/// }
+/// let f = FisherF::new(2.0, 32.0);
+/// let v = f.ind_sample(&mut rand::task_rng());
+/// println!("{} is from an F(2, 32) distribution", v)
 /// ```
 pub struct FisherF {
     priv numer: ChiSquared,
@@ -283,11 +277,9 @@ impl IndependentSample<f64> for FisherF {
 /// use std::rand;
 /// use std::rand::distributions::{StudentT, IndependentSample};
 ///
-/// fn main() {
-///     let t = StudentT::new(11.0);
-///     let v = t.ind_sample(&mut rand::task_rng());
-///     println!("{} is from a t(11) distribution", v)
-/// }
+/// let t = StudentT::new(11.0);
+/// let v = t.ind_sample(&mut rand::task_rng());
+/// println!("{} is from a t(11) distribution", v)
 /// ```
 pub struct StudentT {
     priv chi: ChiSquared,

src/libstd/rand/distributions/mod.rs

@@ -94,15 +94,13 @@ pub struct Weighted<T> {
 /// use std::rand;
 /// use std::rand::distributions::{Weighted, WeightedChoice, IndependentSample};
 ///
-/// fn main() {
-///     let wc = WeightedChoice::new(~[Weighted { weight: 2, item: 'a' },
-///                                    Weighted { weight: 4, item: 'b' },
-///                                    Weighted { weight: 1, item: 'c' }]);
-///     let mut rng = rand::task_rng();
-///     for _ in range(0, 16) {
-///          // on average prints 'a' 4 times, 'b' 8 and 'c' twice.
-///          println!("{}", wc.ind_sample(&mut rng));
-///     }
+/// let wc = WeightedChoice::new(~[Weighted { weight: 2, item: 'a' },
+///                                Weighted { weight: 4, item: 'b' },
+///                                Weighted { weight: 1, item: 'c' }]);
+/// let mut rng = rand::task_rng();
+/// for _ in range(0, 16) {
+///      // on average prints 'a' 4 times, 'b' 8 and 'c' twice.
+///      println!("{}", wc.ind_sample(&mut rng));
 /// }
 /// ```
 pub struct WeightedChoice<T> {

src/libstd/rand/distributions/normal.rs

@@ -76,12 +76,10 @@ impl Rand for StandardNormal {
 /// use std::rand;
 /// use std::rand::distributions::{Normal, IndependentSample};
 ///
-/// fn main() {
-///     // mean 2, standard deviation 3
-///     let normal = Normal::new(2.0, 3.0);
-///     let v = normal.ind_sample(&mut rand::task_rng());
-///     println!("{} is from a N(2, 9) distribution", v)
-/// }
+/// // mean 2, standard deviation 3
+/// let normal = Normal::new(2.0, 3.0);
+/// let v = normal.ind_sample(&mut rand::task_rng());
+/// println!("{} is from a N(2, 9) distribution", v)
 /// ```
 pub struct Normal {
     priv mean: f64,
@@ -120,12 +118,10 @@ impl IndependentSample<f64> for Normal {
 /// use std::rand;
 /// use std::rand::distributions::{LogNormal, IndependentSample};
 ///
-/// fn main() {
-///     // mean 2, standard deviation 3
-///     let log_normal = LogNormal::new(2.0, 3.0);
-///     let v = log_normal.ind_sample(&mut rand::task_rng());
-///     println!("{} is from an ln N(2, 9) distribution", v)
-/// }
+/// // mean 2, standard deviation 3
+/// let log_normal = LogNormal::new(2.0, 3.0);
+/// let v = log_normal.ind_sample(&mut rand::task_rng());
+/// println!("{} is from an ln N(2, 9) distribution", v)
 /// ```
 pub struct LogNormal {
     priv norm: Normal