From 4819253412022a675da85f90b9539afe0fa28536 Mon Sep 17 00:00:00 2001
From: Josh Stone <cuviper@gmail.com>
Date: Tue, 1 Dec 2020 17:53:54 -0800
Subject: [PATCH] Document the first/last methods

---
 src/map.rs | 12 ++++++++++++
 src/set.rs |  6 ++++++
 2 files changed, 18 insertions(+)

diff --git a/src/map.rs b/src/map.rs
index 99096e6008..532791cfd2 100644
--- a/src/map.rs
+++ b/src/map.rs
@@ -717,18 +717,30 @@ 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)
     }
 
+    /// 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)
     }
 
+    /// 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)
     }
diff --git a/src/set.rs b/src/set.rs
index af1ef451c7..29fb64f02c 100644
--- a/src/set.rs
+++ b/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)
     }