---

yaml
---
r: 28483
b: refs/heads/try
c: 37cf649
h: refs/heads/master
i:
  28481: 55393dd
  28479: 13ef407
v: v3

Author: graydon

[refs]

@@ -2,7 +2,7 @@
 refs/heads/master: cd6f24f9d14ac90d167386a56e7a6ac1f0318195
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: cd6f24f9d14ac90d167386a56e7a6ac1f0318195
-refs/heads/try: 7a6df9c90ff1042c07bf785b724884fb84df195f
+refs/heads/try: 37cf649311bcf6fec2d9096b483ac4be81b70732
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df

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