API: Remove deprecation warnings on the removal methods again

Note, these methods are never scheduled to be removed. The warning was
intended to guide the user towards being more explicit about which
removal type they wanted.

However, seeing how indexmap can be used as a drop in solution for
HashMap, I again am dubious that these warnings should be there.

Documentation for the methods has been improved.

Author: bluss

src/map.rs

@@ -664,7 +664,9 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
         replace(self.get_mut(), value)
     }
 
-    #[deprecated(note = "use `swap_remove` or `shift_remove`")]
+    /// Remove the key, value pair stored in the map for this entry, and return the value.
+    ///
+    /// **NOTE:** This is equivalent to `.swap_remove()`.
     pub fn remove(self) -> V {
         self.swap_remove()
     }
@@ -692,7 +694,8 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
     }
 
     /// Remove and return the key, value pair stored in the map for this entry
-    #[deprecated(note = "use `swap_remove_entry` or `shift_remove_entry`")]
+    ///
+    /// **NOTE:** This is equivalent to `.swap_remove_entry()`.
     pub fn remove_entry(self) -> (K, V) {
         self.swap_remove_entry()
     }
@@ -998,10 +1001,14 @@ impl<K, V, S> IndexMap<K, V, S>
         self.core.find_using(h, move |entry| { Q::equivalent(key, &entry.key) })
     }
 
-    /// NOTE: Same as .swap_remove
+    /// Remove the key-value pair equivalent to `key` and return
+    /// its value.
+    ///
+    /// **NOTE:** This is equivalent to `.swap_remove(key)`, if you need to
+    /// preserve the order of the keys in the map, use `.shift_remove(key)`
+    /// instead.
     ///
     /// Computes in **O(1)** time (average).
-    #[deprecated(note = "use `swap_remove`")]
     pub fn remove<Q: ?Sized>(&mut self, key: &Q) -> Option<V>
         where Q: Hash + Equivalent<K>,
     {

src/set.rs

@@ -306,10 +306,12 @@ impl<T, S> IndexSet<T, S>
         }
     }
 
-    /// FIXME Same as .swap_remove
+    /// Remove the value from the set, and return `true` if it was present.
+    ///
+    /// **NOTE:** This is equivalent to `.swap_remove(value)`, if you want
+    /// to preserve the order of the values in the set, use `.shift_remove(value)`.
     ///
     /// Computes in **O(1)** time (average).
-    #[deprecated(note = "use `swap_remove` or `shift_remove`")]
     pub fn remove<Q: ?Sized>(&mut self, value: &Q) -> bool
         where Q: Hash + Equivalent<T>,
     {
@@ -346,10 +348,14 @@ impl<T, S> IndexSet<T, S>
         self.map.shift_remove(value).is_some()
     }
 
-    /// FIXME Same as .swap_take
+    /// Removes and returns the value in the set, if any, that is equal to the
+    /// given one.
+    ///
+    /// **NOTE:** This is equivalent to `.swap_take(value)`, if you need to
+    /// preserve the order of the values in the set, use `.shift_take(value)`
+    /// instead.
     ///
     /// Computes in **O(1)** time (average).
-    #[deprecated(note = "use `swap_take` or `shift_take`")]
     pub fn take<Q: ?Sized>(&mut self, value: &Q) -> Option<T>
         where Q: Hash + Equivalent<T>,
     {