From f45a1dbf1d1eaba511b6673c5955aa108430c165 Mon Sep 17 00:00:00 2001
From: Grzegorz Adam Hankiewicz <gradha@imap.cc>
Date: Fri, 6 Jun 2014 20:58:51 +0200
Subject: Adds brief intro to hashes module.

---
 lib/pure/hashes.nim | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/lib/pure/hashes.nim b/lib/pure/hashes.nim
index 5784a96c1..740355e55 100644
--- a/lib/pure/hashes.nim
+++ b/lib/pure/hashes.nim
@@ -8,7 +8,34 @@
 #
 
 ## This module implements efficient computations of hash values for diverse
-## Nimrod types.
+## Nimrod types. All the procs are based on these two building blocks: the `!&
+## proc <#!&>`_ used to start or mix a hash value, and the `!$ proc <#!$>`_
+## used to *finish* the hash value.  If you want to implement hash procs for
+## your custom types you will end up writing the following kind of skeleton of
+## code:
+##
+## .. code-block:: nimrod
+##  proc hash(x: Something): THash =
+##    ## Computes a THash from `x`.
+##    var h: THash = 0
+##    # Iterate over parts of `x`.
+##    for xAtom in x:
+##      # Mix the atom with the partial hash.
+##      h = h !& xAtom
+##    # Finish the hash.
+##    result = !$h
+##
+## If your custom types contain fields for which there already is a hash proc,
+## like for example objects made up of ``strings``, you can simply hash
+## together the hash value of the individual fields:
+##
+## .. code-block:: nimrod
+##  proc hash(x: Something): THash =
+##    ## Computes a THash from `x`.
+##    var h: THash = 0
+##    h = h &! hash(x.foo)
+##    h = h &! hash(x.bar)
+##    result = !$h
 
 import 
   strutils
-- 
cgit 1.4.1-2-gfad0