From dff14069c966ad4e4c453a84a42579a846d4863b Mon Sep 17 00:00:00 2001
From: Jonas Hietala <tradet.h@gmail.com>
Date: Thu, 24 Jul 2014 15:46:55 +0200
Subject: [PATCH] Document SmallIntMap with examples.

---
 src/libcollections/smallintmap.rs | 121 +++++++++++++++++++++++++++++-
 1 file changed, 119 insertions(+), 2 deletions(-)

diff --git a/src/libcollections/smallintmap.rs b/src/libcollections/smallintmap.rs
index 7c102e35b250..3bc2dbe5cbbb 100644
--- a/src/libcollections/smallintmap.rs
+++ b/src/libcollections/smallintmap.rs
@@ -24,7 +24,39 @@ use {Collection, Mutable, Map, MutableMap, MutableSeq};
 use {vec, slice};
 use vec::Vec;
 
-#[allow(missing_doc)]
+/// A map optimized for small integer keys.
+///
+/// # Example
+///
+/// ```
+/// use std::collections::SmallIntMap;
+///
+/// let mut months = SmallIntMap::new();
+/// months.insert(1, "Jan");
+/// months.insert(2, "Feb");
+/// months.insert(3, "Mar");
+///
+/// if !months.contains_key(&12) {
+///     println!("The end is near!");
+/// }
+///
+/// assert_eq!(months.find(&1), Some(&"Jan"));
+///
+/// match months.find_mut(&3) {
+///     Some(value) => *value = "Venus",
+///     None => (),
+/// }
+///
+/// assert_eq!(months.find(&3), Some(&"Venus"));
+///
+/// // Print out all months
+/// for (key, value) in months.iter() {
+///     println!("month {} is {}", key, value);
+/// }
+///
+/// months.clear();
+/// assert!(months.is_empty());
+/// ```
 pub struct SmallIntMap<T> {
     v: Vec<Option<T>>,
 }
@@ -120,19 +152,66 @@ impl<V> Default for SmallIntMap<V> {
 
 impl<V> SmallIntMap<V> {
     /// Create an empty SmallIntMap.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::SmallIntMap;
+    /// let mut map: SmallIntMap<&str> = SmallIntMap::new();
+    /// ```
     pub fn new() -> SmallIntMap<V> { SmallIntMap{v: vec!()} }
 
-    /// Create an empty SmallIntMap with capacity `capacity`.
+    /// Create an empty SmallIntMap with space for at least `capacity` elements
+    /// before resizing.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::SmallIntMap;
+    /// let mut map: SmallIntMap<&str> = SmallIntMap::with_capacity(10);
+    /// ```
     pub fn with_capacity(capacity: uint) -> SmallIntMap<V> {
         SmallIntMap { v: Vec::with_capacity(capacity) }
     }
 
+    /// Retrieves a value for the given key.
+    /// See [`find`](../trait.Map.html#tymethod.find) for a non-failing alternative.
+    ///
+    /// # Failure
+    ///
+    /// Fails if the key is not present.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::SmallIntMap;
+    ///
+    /// let mut map = SmallIntMap::new();
+    /// map.insert(1, "a");
+    /// assert_eq!(map.get(&1), &"a");
+    /// ```
     pub fn get<'a>(&'a self, key: &uint) -> &'a V {
         self.find(key).expect("key not present")
     }
 
     /// An iterator visiting all key-value pairs in ascending order by the keys.
     /// Iterator element type is `(uint, &'r V)`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::SmallIntMap;
+    ///
+    /// let mut map = SmallIntMap::new();
+    /// map.insert(1, "a");
+    /// map.insert(3, "c");
+    /// map.insert(2, "b");
+    ///
+    /// // Print `1: a` then `2: b` then `3: c`
+    /// for (key, value) in map.iter() {
+    ///     println!("{}: {}", key, value);
+    /// }
+    /// ```
     pub fn iter<'r>(&'r self) -> Entries<'r, V> {
         Entries {
             front: 0,
@@ -144,6 +223,25 @@ impl<V> SmallIntMap<V> {
     /// An iterator visiting all key-value pairs in ascending order by the keys,
     /// with mutable references to the values
     /// Iterator element type is `(uint, &'r mut V)`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::SmallIntMap;
+    ///
+    /// let mut map = SmallIntMap::new();
+    /// map.insert(1, "a");
+    /// map.insert(2, "b");
+    /// map.insert(3, "c");
+    ///
+    /// for (key, value) in map.mut_iter() {
+    ///     *value = "x";
+    /// }
+    ///
+    /// for (key, value) in map.iter() {
+    ///     assert_eq!(value, &"x");
+    /// }
+    /// ```
     pub fn mut_iter<'r>(&'r mut self) -> MutEntries<'r, V> {
         MutEntries {
             front: 0,
@@ -153,6 +251,22 @@ impl<V> SmallIntMap<V> {
     }
 
     /// Empties the hash map, moving all values into the specified closure.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::SmallIntMap;
+    ///
+    /// let mut map = SmallIntMap::new();
+    /// map.insert(1, "a");
+    /// map.insert(3, "c");
+    /// map.insert(2, "b");
+    ///
+    /// // Not possible with .iter()
+    /// let vec: Vec<(uint, &str)> = map.move_iter().collect();
+    ///
+    /// assert_eq!(vec, vec![(1, "a"), (2, "b"), (3, "c")]);
+    /// ```
     pub fn move_iter(&mut self)
         -> FilterMap<(uint, Option<V>), (uint, V),
                 Enumerate<vec::MoveItems<Option<V>>>>
@@ -247,6 +361,7 @@ macro_rules! double_ended_iterator {
     }
 }
 
+/// Forward iterator over a map.
 pub struct Entries<'a, T> {
     front: uint,
     back: uint,
@@ -256,6 +371,8 @@ pub struct Entries<'a, T> {
 iterator!(impl Entries -> (uint, &'a T), get_ref)
 double_ended_iterator!(impl Entries -> (uint, &'a T), get_ref)
 
+/// Forward iterator over the key-value pairs of a map, with the
+/// values being mutable.
 pub struct MutEntries<'a, T> {
     front: uint,
     back: uint,