Merge pull request #1251 from gradha/pr_misc_docs

Misc docs suggestions

lib/pure/algorithm.nim

@@ -150,6 +150,15 @@ proc sort*[T](a: var openArray[T],
   ##    # overload:
   ##    sort(myStrArray, system.cmp)
   ##
+  ## You can inline adhoc comparison procs with the `do notation
+  ## <manual.html#do-notation>`_. Example:
+  ##
+  ## .. code-block:: nimrod
+  ##
+  ##   people.sort do (x, y: Person) -> int:
+  ##     result = cmp(x.surname, y.surname)
+  ##     if result == 0:
+  ##       result = cmp(x.name, y.name)
   var n = a.len
   var b: seq[T]
   newSeq(b, n div 2)

lib/pure/collections/tables.nim

@@ -37,7 +37,8 @@
 ##     ## Piggyback on the already available string hash proc.
 ##     ##
 ##     ## Without this proc nothing works!
-##     result = hash(x.firstName & x.lastName)
+##     result = x.firstName.hash !& x.lastName.hash
+##     result = !$result
 ##
 ##   var
 ##     salaries = initTable[Person, int]()
@@ -848,7 +849,8 @@ when isMainModule:
     ## Piggyback on the already available string hash proc.
     ##
     ## Without this proc nothing works!
-    result = hash(x.firstName & x.lastName)
+    result = x.firstName.hash !& x.lastName.hash
+    result = !$result
 
   var
     salaries = initTable[Person, int]()

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