auto merge of #15806 : treeman/rust/std-doc, r=alexcrichton

Used `HashMap` and `HashSet` as the base of most examples. Could change it up with different containers, but I don't think it's a big deal.

Author: bors

src/libcollections/lib.rs

@@ -73,16 +73,46 @@ mod deque;
 /// A trait to represent mutable containers
 pub trait Mutable: Collection {
     /// Clear the container, removing all values.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// let mut v = vec![1i, 2, 3];
+    /// v.clear();
+    /// assert!(v.is_empty());
+    /// ```
     fn clear(&mut self);
 }
 
 /// A map is a key-value store where values may be looked up by their keys. This
 /// trait provides basic operations to operate on these stores.
 pub trait Map<K, V>: Collection {
-    /// Return a reference to the value corresponding to the key
+    /// Return a reference to the value corresponding to the key.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map = HashMap::new();
+    /// map.insert("a", 1i);
+    /// assert_eq!(map.find(&"a"), Some(&1i));
+    /// assert_eq!(map.find(&"b"), None);
+    /// ```
     fn find<'a>(&'a self, key: &K) -> Option<&'a V>;
 
-    /// Return true if the map contains a value for the specified key
+    /// Return true if the map contains a value for the specified key.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map = HashMap::new();
+    /// map.insert("a", 1i);
+    /// assert_eq!(map.contains_key(&"a"), true);
+    /// assert_eq!(map.contains_key(&"b"), false);
+    /// ```
     #[inline]
     fn contains_key(&self, key: &K) -> bool {
         self.find(key).is_some()
@@ -94,45 +124,164 @@ pub trait MutableMap<K, V>: Map<K, V> + Mutable {
     /// Insert a key-value pair into the map. An existing value for a
     /// key is replaced by the new value. Return true if the key did
     /// not already exist in the map.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map = HashMap::new();
+    /// assert_eq!(map.insert("key", 2i), true);
+    /// assert_eq!(map.insert("key", 9i), false);
+    /// assert_eq!(map.get(&"key"), &9i);
+    /// ```
     #[inline]
     fn insert(&mut self, key: K, value: V) -> bool {
         self.swap(key, value).is_none()
     }
 
     /// Remove a key-value pair from the map. Return true if the key
     /// was present in the map, otherwise false.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map = HashMap::new();
+    /// assert_eq!(map.remove(&"key"), false);
+    /// map.insert("key", 2i);
+    /// assert_eq!(map.remove(&"key"), true);
+    /// ```
     #[inline]
     fn remove(&mut self, key: &K) -> bool {
         self.pop(key).is_some()
     }
 
     /// Insert a key-value pair from the map. If the key already had a value
     /// present in the map, that value is returned. Otherwise None is returned.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map = HashMap::new();
+    /// assert_eq!(map.swap("a", 37i), None);
+    /// assert_eq!(map.is_empty(), false);
+    ///
+    /// map.insert("a", 1i);
+    /// assert_eq!(map.swap("a", 37i), Some(1i));
+    /// assert_eq!(map.get(&"a"), &37i);
+    /// ```
     fn swap(&mut self, k: K, v: V) -> Option<V>;
 
     /// Removes a key from the map, returning the value at the key if the key
     /// was previously in the map.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map: HashMap<&str, int> = HashMap::new();
+    /// map.insert("a", 1i);
+    /// assert_eq!(map.pop(&"a"), Some(1i));
+    /// assert_eq!(map.pop(&"a"), None);
+    /// ```
     fn pop(&mut self, k: &K) -> Option<V>;
 
-    /// Return a mutable reference to the value corresponding to the key
+    /// Return a mutable reference to the value corresponding to the key.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashMap;
+    ///
+    /// let mut map = HashMap::new();
+    /// map.insert("a", 1i);
+    /// match map.find_mut(&"a") {
+    ///     Some(x) => *x = 7i,
+    ///     None => (),
+    /// }
+    /// assert_eq!(map.get(&"a"), &7i);
+    /// ```
     fn find_mut<'a>(&'a mut self, key: &K) -> Option<&'a mut V>;
 }
 
 /// A set is a group of objects which are each distinct from one another. This
 /// trait represents actions which can be performed on sets to iterate over
 /// them.
 pub trait Set<T>: Collection {
-    /// Return true if the set contains a value
+    /// Return true if the set contains a value.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashSet;
+    ///
+    /// let set: HashSet<int> = [1i, 2, 3].iter().map(|&x| x).collect();
+    /// assert_eq!(set.contains(&1), true);
+    /// assert_eq!(set.contains(&4), false);
+    /// ```
     fn contains(&self, value: &T) -> bool;
 
     /// Return true if the set has no elements in common with `other`.
     /// This is equivalent to checking for an empty intersection.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashSet;
+    ///
+    /// let a: HashSet<int> = [1i, 2, 3].iter().map(|&x| x).collect();
+    /// let mut b: HashSet<int> = HashSet::new();
+    ///
+    /// assert_eq!(a.is_disjoint(&b), true);
+    /// b.insert(4);
+    /// assert_eq!(a.is_disjoint(&b), true);
+    /// b.insert(1);
+    /// assert_eq!(a.is_disjoint(&b), false);
+    /// ```
     fn is_disjoint(&self, other: &Self) -> bool;
 
-    /// Return true if the set is a subset of another
+    /// Return true if the set is a subset of another.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashSet;
+    ///
+    /// let sup: HashSet<int> = [1i, 2, 3].iter().map(|&x| x).collect();
+    /// let mut set: HashSet<int> = HashSet::new();
+    ///
+    /// assert_eq!(set.is_subset(&sup), true);
+    /// set.insert(2);
+    /// assert_eq!(set.is_subset(&sup), true);
+    /// set.insert(4);
+    /// assert_eq!(set.is_subset(&sup), false);
+    /// ```
     fn is_subset(&self, other: &Self) -> bool;
 
-    /// Return true if the set is a superset of another
+    /// Return true if the set is a superset of another.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashSet;
+    ///
+    /// let sub: HashSet<int> = [1i, 2].iter().map(|&x| x).collect();
+    /// let mut set: HashSet<int> = HashSet::new();
+    ///
+    /// assert_eq!(set.is_superset(&sub), false);
+    ///
+    /// set.insert(0);
+    /// set.insert(1);
+    /// assert_eq!(set.is_superset(&sub), false);
+    ///
+    /// set.insert(2);
+    /// assert_eq!(set.is_superset(&sub), true);
+    /// ```
     fn is_superset(&self, other: &Self) -> bool {
         other.is_subset(self)
     }
@@ -145,10 +294,34 @@ pub trait Set<T>: Collection {
 pub trait MutableSet<T>: Set<T> + Mutable {
     /// Add a value to the set. Return true if the value was not already
     /// present in the set.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashSet;
+    ///
+    /// let mut set = HashSet::new();
+    ///
+    /// assert_eq!(set.insert(2i), true);
+    /// assert_eq!(set.insert(2i), false);
+    /// assert_eq!(set.len(), 1);
+    /// ```
     fn insert(&mut self, value: T) -> bool;
 
     /// Remove a value from the set. Return true if the value was
     /// present in the set.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::HashSet;
+    ///
+    /// let mut set = HashSet::new();
+    ///
+    /// set.insert(2i);
+    /// assert_eq!(set.remove(&2), true);
+    /// assert_eq!(set.remove(&2), false);
+    /// ```
     fn remove(&mut self, value: &T) -> bool;
 }
 

src/libcore/collections.rs

@@ -14,9 +14,23 @@
 /// knowledge known is the number of elements contained within.
 pub trait Collection {
     /// Return the number of elements in the container
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// let a = [1i, 2, 3];
+    /// assert_eq!(a.len(), 3);
+    /// ```
     fn len(&self) -> uint;
 
     /// Return true if the container contains no elements
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// let s = String::new();
+    /// assert!(s.is_empty());
+    /// ```
     #[inline]
     fn is_empty(&self) -> bool {
         self.len() == 0

src/libcore/default.rs

@@ -15,6 +15,16 @@
 /// A trait that types which have a useful default value should implement.
 pub trait Default {
     /// Return the "default value" for a type.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::default::Default;
+    ///
+    /// let i: i8 = Default::default();
+    /// let (x, y): (Option<String>, f64) = Default::default();
+    /// let (a, b, (c, d)): (int, uint, (bool, bool)) = Default::default();
+    /// ```
     fn default() -> Self;
 }