Merge pull request #1251 from gradha/pr_misc_docs

Misc docs suggestions

4 files changed, 90 insertions, 9 deletions

diff --git a/lib/pure/algorithm.nim b/lib/pure/algorithm.nim
index 37fbc948c..86d329763 100644
--- a/lib/pure/algorithm.nim
+++ b/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)
diff --git a/lib/pure/collections/tables.nim b/lib/pure/collections/tables.nim
index 091bf8590..ce9df09e1 100644
--- a/lib/pure/collections/tables.nim
+++ b/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]()
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
diff --git a/lib/system.nim b/lib/system.nim
index c69a335e4..2f24f68b1 100644
--- a/lib/system.nim
+++ b/lib/system.nim
@@ -88,6 +88,15 @@ proc defined*(x: expr): bool {.magic: "Defined", noSideEffect.}
   ##   when not defined(strutils.toUpper):
   ##     # provide our own toUpper proc here, because strutils is
   ##     # missing it.
+  ##
+  ## You can also check external symbols introduced through the compiler's
+  ## `-d:x switch <nimrodc.html#compile-time-symbols>`_ to enable build time
+  ## conditionals:
+  ##
+  ## .. code-block:: Nimrod
+  ##   when not defined(release):
+  ##     # Do here programmer friendly expensive sanity checks.
+  ##   # Put here the normal code
 
 when defined(useNimRtl):
   {.deadCodeElim: on.}
@@ -1767,9 +1776,38 @@ iterator fields*[S:tuple|object, T:tuple|object](x: S, y: T): tuple[a,b: expr] {
   ## in the loop body.
 iterator fieldPairs*[T: tuple|object](x: T): TObject {.
   magic: "FieldPairs", noSideEffect.}
-  ## iterates over every field of `x`. Warning: This really transforms
-  ## the 'for' and unrolls the loop. The current implementation also has a bug
-  ## that affects symbol binding in the loop body.
+  ## Iterates over every field of `x` returning their name and value.
+  ##
+  ## When you iterate over objects with different field types you have to use
+  ## the compile time ``when`` instead of a runtime ``if`` to select the code
+  ## you want to run for each type. To perform the comparison use the `is
+  ## operator <manual.html#is-operator>`_. Example:
+  ##
+  ## .. code-block:: Nimrod
+  ##
+  ##   type
+  ##     Custom = object
+  ##       foo: string
+  ##       bar: bool
+  ##
+  ##   proc `$`(x: Custom): string =
+  ##     result = "Custom:"
+  ##     for name, value in x.fieldPairs:
+  ##       when value is bool:
+  ##         result.add("\n\t" & name & " is " & $value)
+  ##       else:
+  ##         if value.isNil:
+  ##           result.add("\n\t" & name & " (nil)")
+  ##         else:
+  ##           result.add("\n\t" & name & " '" & value & "'")
+  ##
+  ## Another way to do the same without ``when`` is to leave the task of
+  ## picking the appropriate code to a secondary proc which you overload for
+  ## each field type and pass the `value` to.
+  ##
+  ## Warning: This really transforms the 'for' and unrolls the loop. The
+  ## current implementation also has a bug that affects symbol binding in the
+  ## loop body.
 iterator fieldPairs*[S: tuple|object, T: tuple|object](x: S, y: T): tuple[
   a, b: expr] {.
   magic: "FieldPairs", noSideEffect.}
@@ -2783,10 +2821,15 @@ when true:
     THide(raiseAssert)(msg)
 
 template assert*(cond: bool, msg = "") =
-  ## provides a means to implement `programming by contracts`:idx: in Nimrod.
+  ## Raises ``EAssertionFailure`` with `msg` if `cond` is false.
+  ##
+  ## Provides a means to implement `programming by contracts`:idx: in Nimrod.
   ## ``assert`` evaluates expression ``cond`` and if ``cond`` is false, it
-  ## raises an ``EAssertionFailure`` exception. However, the compiler may
-  ## not generate any code at all for ``assert`` if it is advised to do so.
+  ## raises an ``EAssertionFailure`` exception. However, the compiler may not
+  ## generate any code at all for ``assert`` if it is advised to do so through
+  ## the ``-d:release`` or ``--assertions:off`` `command line switches
+  ## <nimrodc.html#command-line-switches>`_.
+  ##
   ## Use ``assert`` for debugging purposes only.
   bind instantiationInfo
   mixin failedAssertImpl