---

yaml
---
r: 122675
b: refs/heads/snap-stage3
c: d90b71c
h: refs/heads/master
i:
  122673: 12bee04
  122671: afbd8cc
v: v3

Author: erickt

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 1bff1ff810dcfa8064c11e2b84473f053d1f69f1
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: c1ff089c275592044057841673256ec78d6c400c
+refs/heads/snap-stage3: d90b71cff68ec3748b9f42063513773da57e01e2
 refs/heads/try: 2e9d9477b848cec778ca3f07ecdf0aea6ade23de
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/src/libstd/hash.rs

@@ -8,7 +8,58 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Generic hashing support.
+/*!
+ * Generic hashing support.
+ *
+ * This module provides a generic way to compute the hash of a value. The
+ * simplest way to make a type hashable is to use `#[deriving(Hash)]`:
+ *
+ * # Example
+ *
+ * ```rust
+ * use std::hash;
+ * use std::hash::Hash;
+ *
+ * #[deriving(Hash)]
+ * struct Person {
+ *     id: uint,
+ *     name: String,
+ *     phone: u64,
+ * }
+ *
+ * let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 };
+ * let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 };
+ *
+ * assert!(hash::hash(&person1) != hash::hash(&person2));
+ * ```
+ *
+ * If you need more control over how a value is hashed, you need to implement
+ * the trait `Hash`:
+ *
+ * ```rust
+ * use std::hash;
+ * use std::hash::Hash;
+ * use std::hash::sip::SipState;
+ *
+ * struct Person {
+ *     id: uint,
+ *     name: String,
+ *     phone: u64,
+ * }
+ *
+ * impl Hash for Person {
+ *     fn hash(&self, state: &mut SipState) {
+ *         self.id.hash(state);
+ *         self.phone.hash(state);
+ *     }
+ * }
+ *
+ * let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 };
+ * let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 };
+ *
+ * assert!(hash::hash(&person1) == hash::hash(&person2));
+ * ```
+ */
 
 pub use core_collections::hash::{Hash, Hasher, Writer, hash, sip};