---

yaml
---
r: 30505
b: refs/heads/incoming
c: 37cf649
h: refs/heads/master
i:
  30503: dea0a7f
v: v3

Author: graydon

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 7a6df9c90ff1042c07bf785b724884fb84df195f
+refs/heads/incoming: 37cf649311bcf6fec2d9096b483ac4be81b70732
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/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;

branches/incoming/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;
 }
 

branches/incoming/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);
 }