Document the first/last methods

Author: cuviper

src/map.rs

@@ -717,20 +717,32 @@ impl<K, V, S> IndexMap<K, V, S> {
         self.as_entries_mut().get_mut(index).map(Bucket::muts)
     }
 
+    /// Get the first key-value pair
+    ///
+    /// Computes in **O(1)** time.
     pub fn first(&self) -> Option<(&K, &V)> {
         self.as_entries().first().map(Bucket::refs)
     }
 
-    pub fn first_mut(&mut self) -> Option<(&mut K, &mut V)> {
-        self.as_entries_mut().first_mut().map(Bucket::muts)
+    /// Get the first key-value pair, with mutable access to the value
+    ///
+    /// Computes in **O(1)** time.
+    pub fn first_mut(&mut self) -> Option<(&K, &mut V)> {
+        self.as_entries_mut().first_mut().map(Bucket::ref_mut)
     }
 
+    /// Get the last key-value pair
+    ///
+    /// Computes in **O(1)** time.
     pub fn last(&self) -> Option<(&K, &V)> {
         self.as_entries().last().map(Bucket::refs)
     }
 
-    pub fn last_mut(&mut self) -> Option<(&mut K, &mut V)> {
-        self.as_entries_mut().last_mut().map(Bucket::muts)
+    /// Get the last key-value pair, with mutable access to the value
+    ///
+    /// Computes in **O(1)** time.
+    pub fn last_mut(&mut self) -> Option<(&K, &mut V)> {
+        self.as_entries_mut().last_mut().map(Bucket::ref_mut)
     }
 
     /// Remove the key-value pair by index

src/set.rs

@@ -602,10 +602,16 @@ impl<T, S> IndexSet<T, S> {
         self.as_entries().get(index).map(Bucket::key_ref)
     }
 
+    /// Get the first value
+    ///
+    /// Computes in **O(1)** time.
     pub fn first(&self) -> Option<&T> {
         self.as_entries().first().map(Bucket::key_ref)
     }
 
+    /// Get the last value
+    ///
+    /// Computes in **O(1)** time.
     pub fn last(&self) -> Option<&T> {
         self.as_entries().last().map(Bucket::key_ref)
     }