doc: Enhance doctests for index set/map methods

- Newly introduced examples and comments for key functions in `index_set.rs` like `insert`, `insert_full`, `get`, `get_full`, and `get_index`.
- Improved `FrozenIndexMap` class in `index_map.rs` by adding examples and documentation for the `insert`, `insert_full`, and `get_index` methods.

src/index_map.rs

@@ -34,6 +34,24 @@ impl<K: Eq + Hash, V> FrozenIndexMap<K, V> {
 impl<K: Eq + Hash, V: StableDeref, S: BuildHasher> FrozenIndexMap<K, V, S> {
     // these should never return &K or &V
     // these should never delete any entries
+    //
+    /// If the key exists in the map, returns a reference to the corresponding
+    /// value, otherwise inserts a new entry in the map for that key
+    /// and returns a reference to the generated value.
+    ///
+    /// Existing values are never overwritten.
+    ///
+    /// The key may be any borrowed form of the map's key type, but
+    /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
+    /// the key type.
+    ///
+    /// # Example
+    /// ```
+    /// use elsa::index_map::FrozenIndexMap;
+    /// let map = FrozenIndexMap::new();
+    /// assert_eq!(map.insert(1, Box::new("a")), &"a");
+    /// assert_eq!(map.insert(1, Box::new("b")), &"a");
+    /// ```
     pub fn insert(&self, k: K, v: V) -> &V::Target {
         assert!(!self.in_use.get());
         self.in_use.set(true);
@@ -47,6 +65,24 @@ impl<K: Eq + Hash, V: StableDeref, S: BuildHasher> FrozenIndexMap<K, V, S> {
 
     // these should never return &K or &V
     // these should never delete any entries
+    //
+    /// If the key exists in the map, returns a reference to the corresponding
+    /// value and its index, otherwise inserts a new entry in the map for that key
+    /// and returns a reference to the generated value and its index.
+    ///
+    /// Existing values are never overwritten.
+    ///
+    /// The key may be any borrowed form of the map's key type, but
+    /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
+    /// the key type.
+    ///
+    /// # Example
+    /// ```
+    /// use elsa::index_map::FrozenIndexMap;
+    /// let map = FrozenIndexMap::new();
+    /// assert_eq!(map.insert_full(12, Box::new("a")), (0, &"a"));
+    /// assert_eq!(map.insert_full(12, Box::new("b")), (0, &"a"));
+    /// ```
     pub fn insert_full(&self, k: K, v: V) -> (usize, &V::Target) {
         assert!(!self.in_use.get());
         self.in_use.set(true);
@@ -91,6 +127,23 @@ impl<K: Eq + Hash, V: StableDeref, S: BuildHasher> FrozenIndexMap<K, V, S> {
         ret
     }
 
+    /// Returns a reference to the key-value mapping corresponding to an index.
+    ///
+    /// The key may be any borrowed form of the map's key type, but
+    /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for
+    /// the key type.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use elsa::index_map::FrozenIndexMap;
+    ///
+    /// let map = FrozenIndexMap::new();
+    /// let (idx, _ref) = map.insert_full(Box::new("foo"), Box::new("a"));
+    /// assert_eq!(idx, 0);
+    /// assert_eq!(map.get_index(idx), Some((&"foo", &"a")));
+    /// assert_eq!(map.get_index(idx + 1), None);
+    /// ```
     pub fn get_index(&self, index: usize) -> Option<(&K::Target, &V::Target)>
     where
         K: StableDeref,

src/index_set.rs

@@ -31,6 +31,24 @@ impl<T: Eq + Hash> FrozenIndexSet<T> {
 impl<T: Eq + Hash + StableDeref, S: BuildHasher> FrozenIndexSet<T, S> {
     // these should never return &T
     // these should never delete any entries
+    //
+    /// If the value exists in the set, returns a reference to the corresponding
+    /// value, otherwise inserts a new entry in the set for that value
+    /// and returns a reference to it.
+    ///
+    /// Existing values are never overwritten.
+    ///
+    /// # Example
+    /// ```
+    /// use elsa::index_set::FrozenIndexSet;
+    /// let set = FrozenIndexSet::new();
+    /// let a_ref = set.insert(Box::new("a"));
+    /// let aa = "a";
+    /// let other_a_ref = unsafe { aa.as_ptr() as *const &str};
+    /// let other_a = Box::new(aa);
+    /// assert!(!std::ptr::eq(a_ref, other_a_ref));
+    /// assert!(std::ptr::eq(a_ref, set.insert(other_a)));
+    /// ```
     pub fn insert(&self, value: T) -> &T::Target {
         assert!(!self.in_use.get());
         self.in_use.set(true);
@@ -45,6 +63,19 @@ impl<T: Eq + Hash + StableDeref, S: BuildHasher> FrozenIndexSet<T, S> {
 
     // these should never return &T
     // these should never delete any entries
+    /// If the key exists in the set, returns a reference to the corresponding
+    /// value and its index, otherwise inserts a new entry in the set for that value
+    /// and returns a reference to it and its index.
+    ///
+    /// Existing values are never overwritten.
+    ///
+    /// # Example
+    /// ```
+    /// use elsa::index_set::FrozenIndexSet;
+    /// let map = FrozenIndexSet::new();
+    /// assert_eq!(map.insert_full(Box::new("a")), (0, &"a"));
+    /// assert_eq!(map.insert_full(Box::new("b")), (1, &"b"));
+    /// ```
     pub fn insert_full(&self, value: T) -> (usize, &T::Target) {
         assert!(!self.in_use.get());
         self.in_use.set(true);
@@ -84,6 +115,18 @@ impl<T: Eq + Hash + StableDeref, S: BuildHasher> FrozenIndexSet<T, S> {
     //     }
     // }
 
+    /// Returns a reference to the value passed as argument if present in the set.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use elsa::index_set::FrozenIndexSet;
+    ///
+    /// let set = FrozenIndexSet::new();
+    /// set.insert(Box::new("a"));
+    /// assert_eq!(set.get(&Box::new("a")), Some(&"a"));
+    /// assert_eq!(set.get(&Box::new("b")), None);
+    /// ```
     pub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&T::Target>
     where
         T: Borrow<Q>,
@@ -99,6 +142,19 @@ impl<T: Eq + Hash + StableDeref, S: BuildHasher> FrozenIndexSet<T, S> {
         ret
     }
 
+    /// Returns a reference to the value passed as argument if present in the set,
+    /// along with its index
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use elsa::index_set::FrozenIndexSet;
+    ///
+    /// let set = FrozenIndexSet::new();
+    /// set.insert(Box::new("a"));
+    /// assert_eq!(set.get_full(&Box::new("a")), Some((0, &"a")));
+    /// assert_eq!(set.get_full(&Box::new("b")), None);
+    /// ```
     pub fn get_full<Q: ?Sized>(&self, k: &Q) -> Option<(usize, &T::Target)>
     where
         T: Borrow<Q>,
@@ -114,6 +170,19 @@ impl<T: Eq + Hash + StableDeref, S: BuildHasher> FrozenIndexSet<T, S> {
         ret
     }
 
+    /// Returns a reference to value at the index passed as argument, if
+    /// present in the set.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use elsa::index_set::FrozenIndexSet;
+    ///
+    /// let set = FrozenIndexSet::new();
+    /// set.insert(Box::new("a"));
+    /// assert_eq!(set.get_index(0), Some(&"a"));
+    /// assert_eq!(set.get_index(1), None);
+    /// ```
     pub fn get_index(&self, index: usize) -> Option<&T::Target> {
         assert!(!self.in_use.get());
         self.in_use.set(true);