From 4b704ac69b17d8d338c25cdb24f8bcdfbd7565a4 Mon Sep 17 00:00:00 2001
From: Niko Matsakis <niko@alum.mit.edu>
Date: Wed, 7 Dec 2011 08:14:57 -0800
Subject: [PATCH] improve comments

---
 src/libstd/map.rs | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/src/libstd/map.rs b/src/libstd/map.rs
index c581186e4d15..833a7af59570 100644
--- a/src/libstd/map.rs
+++ b/src/libstd/map.rs
@@ -9,7 +9,9 @@ A hashmap
 /*
 Type: hashfn
 
-A function that returns a hash of a value
+A function that returns a hash of a value.
+The hash should concentrate entropy in the
+lower bits.
 */
 type hashfn<K> = fn(K) -> uint;
 
@@ -352,9 +354,15 @@ mod chained {
 }
 
 /*
-Function: mk_hashmap
+Function: mk_flat_hashmap
 
-Construct a hashmap
+Construct a "flat" hashmap, meaning that there are
+not chains per buckets, but rather we search a sequence
+of buckets for each key.
+
+Warning: it is unclear to me that this code is correct
+on 32-bit processors.  Check out the 'hash-tearing' code
+in hash() and the comment surrounding it. - Niko
 
 Parameters:
 
@@ -550,6 +558,16 @@ fn mk_flat_hashmap<copy K, copy V>(hasher: hashfn<K>, eqer: eqfn<K>)
     ret hashmap(hasher, eqer, bkts, initial_capacity, 0u, load_factor);
 }
 
+/*
+Function: mk_hashmap
+
+Construct a hashmap.
+
+Parameters:
+
+hasher - The hash function for key type K
+eqer - The equality function for key type K
+*/
 fn mk_hashmap<copy K, copy V>(hasher: hashfn<K>, eqer: eqfn<K>)
     -> hashmap<K, V> {
     ret chained::mk(hasher, eqer);