From 37cf649311bcf6fec2d9096b483ac4be81b70732 Mon Sep 17 00:00:00 2001
From: Graydon Hoare <graydon@mozilla.com>
Date: Wed, 12 Sep 2012 17:07:46 -0700
Subject: [PATCH] Document IterBytes, Eq, Cmp, Hash. Close #3449.

---
 src/libcore/cmp.rs      | 16 ++++++++++++++++
 src/libcore/hash.rs     | 25 ++++++++++++++++++++++++-
 src/libcore/to_bytes.rs | 21 +++++++++++++++++++++
 3 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs
index 82a830d05cd..4c4efc13859 100644
--- a/src/libcore/cmp.rs
+++ b/src/libcore/cmp.rs
@@ -5,6 +5,14 @@
 /// Interfaces used for comparison.
 
 // Awful hack to work around duplicate lang items in core test.
+
+/**
+ * Trait for values that can be compared for a sort-order.
+ *
+ * Eventually this may be simplified to only require
+ * an `le` method, with the others generated from
+ * default implementations.
+ */
 #[cfg(notest)]
 #[lang="ord"]
 trait Ord {
@@ -24,6 +32,14 @@ trait Ord {
 
 #[cfg(notest)]
 #[lang="eq"]
+/**
+ * Trait for values that can be compared for equality
+ * and inequality.
+ *
+ * Eventually this may be simplified to only require
+ * an `eq` method, with the other generated from
+ * a default implementation.
+ */
 trait Eq {
     pure fn eq(&&other: self) -> bool;
     pure fn ne(&&other: self) -> bool;
diff --git a/src/libcore/hash.rs b/src/libcore/hash.rs
index 13fef207fac..1dec739dd21 100644
--- a/src/libcore/hash.rs
+++ b/src/libcore/hash.rs
@@ -34,8 +34,31 @@ export hash_u16;
 export hash_u8;
 export hash_uint;
 
-/// Types that can meaningfully be hashed should implement this.
+/**
+ * Types that can meaningfully be hashed should implement this.
+ *
+ * Note that this trait is likely to change somewhat as it is
+ * closely related to `to_bytes::IterBytes` and in almost all
+ * cases presently the two are (and must be) used together.
+ *
+ * In general, most types only need to implement `IterBytes`,
+ * and the implementation of `Hash` below will take care of
+ * the rest. This is the recommended approach, since constructing
+ * good keyed hash functions is quite difficult.
+ */
 trait Hash {
+    /**
+     * Compute a "keyed" hash of the value implementing the trait,
+     * taking `k0` and `k1` as "keying" parameters that randomize or
+     * otherwise perturb the hash function in such a way that a
+     * hash table built using such "keyed hash functions" cannot
+     * be made to perform linearly by an attacker controlling the
+     * hashtable's contents.
+     *
+     * In practical terms, we implement this using the SipHash 2-4
+     * function and require most types to only implement the
+     * IterBytes trait, that feeds SipHash.
+     */
     pure fn hash_keyed(k0: u64, k1: u64) -> u64;
 }
 
diff --git a/src/libcore/to_bytes.rs b/src/libcore/to_bytes.rs
index 337aa5980d7..3363f5a0a6a 100644
--- a/src/libcore/to_bytes.rs
+++ b/src/libcore/to_bytes.rs
@@ -6,7 +6,28 @@ use io::Writer;
 
 type Cb = fn(buf: &[const u8]) -> bool;
 
+/**
+ * A trait to implement in order to make a type hashable;
+ * This works in combination with the trait `Hash::Hash`, and
+ * may in the future be merged with that trait or otherwise
+ * modified when default methods and trait inheritence are
+ * completed.
+ */
 trait IterBytes {
+    /**
+     * Call the provided callback `f` one or more times with
+     * byte-slices that should be used when computing a hash
+     * value or otherwise "flattening" the structure into
+     * a sequence of bytes. The `lsb0` parameter conveys
+     * whether the caller is asking for little-endian bytes
+     * (`true`) or big-endian (`false`); this should only be
+     * relevant in implementations that represent a single
+     * multi-byte datum such as a 32 bit integer or 64 bit
+     * floating-point value. It can be safely ignored for
+     * larger structured types as they are usually processed
+     * left-to-right in declaration order, regardless of
+     * underlying memory endianness.
+     */
     pure fn iter_bytes(lsb0: bool, f: Cb);
 }