From 0d801a6c24195099c73612cfedeb96db3bead30f Mon Sep 17 00:00:00 2001
From: Josh Stone <cuviper@gmail.com>
Date: Tue, 19 Jan 2021 17:37:54 -0800
Subject: [PATCH] Document all entry methods

---
 src/map/core.rs     | 9 +++++++++
 src/map/core/raw.rs | 7 +++++++
 2 files changed, 16 insertions(+)

diff --git a/src/map/core.rs b/src/map/core.rs
index 9482b2f5..1c261a51 100644
--- a/src/map/core.rs
+++ b/src/map/core.rs
@@ -445,6 +445,9 @@ pub enum Entry<'a, K, V> {
 }
 
 impl<'a, K, V> Entry<'a, K, V> {
+    /// Inserts the given default value in the entry if it is vacant and returns a mutable
+    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
+    ///
     /// Computes in **O(1)** time (amortized average).
     pub fn or_insert(self, default: V) -> &'a mut V {
         match self {
@@ -453,6 +456,9 @@ impl<'a, K, V> Entry<'a, K, V> {
         }
     }
 
+    /// Inserts the result of the `call` function in the entry if it is vacant and returns a mutable
+    /// reference to it. Otherwise a mutable reference to an already existent value is returned.
+    ///
     /// Computes in **O(1)** time (amortized average).
     pub fn or_insert_with<F>(self, call: F) -> &'a mut V
     where
@@ -590,6 +596,7 @@ impl<'a, K, V> VacantEntry<'a, K, V> {
         &self.key
     }
 
+    /// Takes ownership of the key, leaving the entry vacant.
     pub fn into_key(self) -> K {
         self.key
     }
@@ -599,6 +606,8 @@ impl<'a, K, V> VacantEntry<'a, K, V> {
         self.map.len()
     }
 
+    /// Inserts the entry's key and the given value into the map, and returns a mutable reference
+    /// to the value.
     pub fn insert(self, value: V) -> &'a mut V {
         let i = self.map.push(self.hash, self.key, value);
         &mut self.map.entries[i].value
diff --git a/src/map/core/raw.rs b/src/map/core/raw.rs
index be91b3d6..0115b07f 100644
--- a/src/map/core/raw.rs
+++ b/src/map/core/raw.rs
@@ -113,10 +113,15 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
         &self.map.entries[self.index()].key
     }
 
+    /// Gets a reference to the entry's value in the map.
     pub fn get(&self) -> &V {
         &self.map.entries[self.index()].value
     }
 
+    /// Gets a mutable reference to the entry's value in the map.
+    ///
+    /// If you need a reference which may outlive the destruction of the
+    /// `Entry` value, see `into_mut`.
     pub fn get_mut(&mut self) -> &mut V {
         let index = self.index();
         &mut self.map.entries[index].value
@@ -136,6 +141,8 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
         unsafe { self.raw_bucket.read() }
     }
 
+    /// Converts into a mutable reference to the entry's value in the map,
+    /// with a lifetime bound to the map itself.
     pub fn into_mut(self) -> &'a mut V {
         let index = self.index();
         &mut self.map.entries[index].value