From 64adca717fe0f1fac851e9d09972adecf21bf662 Mon Sep 17 00:00:00 2001
From: Piotr Czarnecki <pioczarn@gmail.com>
Date: Tue, 22 Mar 2016 12:52:31 +0100
Subject: [PATCH] f clarification, docs

---
 src/libstd/collections/hash/map.rs   | 5 +++++
 src/libstd/collections/hash/table.rs | 7 +++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index e149a5131fe3..3fb843dc7e1b 100644
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -455,6 +455,11 @@ fn robin_hood<'a, K: 'a, V: 'a>(bucket: FullBucketMut<'a, K, V>,
                     let bucket = bucket.put(hash, key, val);
                     // Now that it's stolen, just read the value's pointer
                     // right out of the table! Go back to the *starting point*.
+                    //
+                    // This use of `into_table` is misleading. It turns the
+                    // bucket, which is a FullBucket on top of a
+                    // FullBucketMut, into just one FullBucketMut. The "table"
+                    // refers to the inner FullBucketMut in this context.
                     return bucket.into_table().into_mut_refs().1;
                 },
                 Full(bucket) => bucket
diff --git a/src/libstd/collections/hash/table.rs b/src/libstd/collections/hash/table.rs
index f3ed2737c879..5802a1fd2656 100644
--- a/src/libstd/collections/hash/table.rs
+++ b/src/libstd/collections/hash/table.rs
@@ -421,8 +421,9 @@ impl<K, V, M: Deref<Target=RawTable<K, V>>> FullBucket<K, V, M> {
     }
 }
 
-// We don't need a `Take` trait currently. This is why a mutable reference
-// to the table is required.
+// We take a mutable reference to the table instead of accepting anything that
+// implements `DerefMut` to prevent fn `take` from being called on `stash`ed
+// buckets.
 impl<'t, K, V> FullBucket<K, V, &'t mut RawTable<K, V>> {
     /// Removes this bucket's key and value from the hashtable.
     ///
@@ -446,6 +447,8 @@ impl<'t, K, V> FullBucket<K, V, &'t mut RawTable<K, V>> {
     }
 }
 
+// This use of `Put` is misleading and restrictive, but safe and sufficient for our use cases
+// where `M` is a full bucket or table reference type with mutable access to the table.
 impl<K, V, M> FullBucket<K, V, M> where M: Put<K, V> {
     pub fn replace(&mut self, h: SafeHash, k: K, v: V) -> (SafeHash, K, V) {
         unsafe {