Merge pull request #187 from Lotterleben/indexDoc

IndexMap, IndexSet: hint to FnvIndex...: Extend explanation, add examples & links

Author: korken89

src/indexmap.rs

@@ -12,7 +12,48 @@ use hash32::{BuildHasher, BuildHasherDefault, FnvHasher, Hash, Hasher};
 
 use crate::Vec;
 
-/// An `IndexMap` using the default FNV hasher
+/// A [`heaples::IndexMap`](./struct.IndexMap.html) using the default FNV hasher
+///
+/// A list of all Methods and Traits available for `FnvIndexMap` can be found in
+/// the [`heapless::IndexMap`](./struct.IndexMap.html) documentation.
+///
+/// # Examples
+/// ```
+/// use heapless::FnvIndexMap;
+/// use heapless::consts::*;
+///
+/// // A hash map with a capacity of 16 key-value pairs allocated on the stack
+/// let mut book_reviews = FnvIndexMap::<_, _, U16>::new();
+///
+/// // review some books.
+/// book_reviews.insert("Adventures of Huckleberry Finn",    "My favorite book.").unwrap();
+/// book_reviews.insert("Grimms' Fairy Tales",               "Masterpiece.").unwrap();
+/// book_reviews.insert("Pride and Prejudice",               "Very enjoyable.").unwrap();
+/// book_reviews.insert("The Adventures of Sherlock Holmes", "Eye lyked it alot.").unwrap();
+///
+/// // 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 {
+///     match book_reviews.get(book) {
+///         Some(review) => println!("{}: {}", book, review),
+///         None => println!("{} is unreviewed.", book)
+///     }
+/// }
+///
+/// // iterate over everything.
+/// for (book, review) in &book_reviews {
+///     println!("{}: \"{}\"", book, review);
+/// }
+/// ```
 pub type FnvIndexMap<K, V, N> = IndexMap<K, V, N, BuildHasherDefault<FnvHasher>>;
 
 #[derive(Clone, Copy, Eq, PartialEq)]
@@ -286,9 +327,15 @@ where
 
 /// Fixed capacity [`IndexMap`](https://docs.rs/indexmap/1/indexmap/map/struct.IndexMap.html)
 ///
+/// Note that you cannot use `IndexMap` directly, since it is generic around the hashing algorithm
+/// in use. Pick a concrete instantiation like [`FnvIndexMap`](./type.FnvIndexMap.html) instead
+/// or create your own.
+///
 /// Note that the capacity of the `IndexMap` must be a power of 2.
 ///
 /// # Examples
+/// Since `IndexMap` cannot be used directly, we're using its `FnvIndexMap` instantiation
+/// for this example.
 ///
 /// ```
 /// use heapless::FnvIndexMap;

src/indexset.rs

@@ -5,14 +5,52 @@ use hash32::{BuildHasher, BuildHasherDefault, FnvHasher, Hash, Hasher};
 
 use crate::indexmap::{self, Bucket, IndexMap, Pos};
 
-/// An `IndexSet` using the default FNV hasher
+/// A [`heapless::IndexSet`](./struct.IndexSet.html) using the
+/// default FNV hasher.
+/// A list of all Methods and Traits available for `FnvIndexSet` can be found in
+/// the [`heapless::IndexSet`](./struct.IndexSet.html) documentation.
+///
+/// # Examples
+/// ```
+/// use heapless::FnvIndexSet;
+/// use heapless::consts::*;
+///
+/// // A hash set with a capacity of 16 elements allocated on the stack
+/// let mut books = FnvIndexSet::<_, U16>::new();
+///
+/// // Add some books.
+/// books.insert("A Dance With Dragons").unwrap();
+/// books.insert("To Kill a Mockingbird").unwrap();
+/// books.insert("The Odyssey").unwrap();
+/// books.insert("The Great Gatsby").unwrap();
+///
+/// // Check for a specific one.
+/// if !books.contains("The Winds of Winter") {
+///     println!("We have {} books, but The Winds of Winter ain't one.",
+///              books.len());
+/// }
+///
+/// // Remove a book.
+/// books.remove("The Odyssey");
+///
+/// // Iterate over everything.
+/// for book in &books {
+///     println!("{}", book);
+/// }
+/// ```
 pub type FnvIndexSet<T, N> = IndexSet<T, N, BuildHasherDefault<FnvHasher>>;
 
-/// Fixed capacity [`IndexSet`](https://docs.rs/indexmap/1/indexmap/set/struct.IndexSet.html)
+/// Fixed capacity [`IndexSet`](https://docs.rs/indexmap/1/indexmap/set/struct.IndexSet.html).
+///
+/// Note that you cannot use `IndexSet` directly, since it is generic around the hashing algorithm
+/// in use. Pick a concrete instantiation like [`FnvIndexSet`](./type.FnvIndexSet.html) instead
+/// or create your own.
 ///
 /// Note that the capacity of the `IndexSet` must be a power of 2.
 ///
 /// # Examples
+/// Since `IndexSet` cannot be used directly, we're using its `FnvIndexSet` instantiation
+/// for this example.
 ///
 /// ```
 /// use heapless::FnvIndexSet;