From 3f9ad7ef22dfea8fa58c378322581ab3b2ff48b2 Mon Sep 17 00:00:00 2001
From: Grzegorz Adam Hankiewicz <gradha@imap.cc>
Date: Fri, 6 Jun 2014 21:55:20 +0200
Subject: [PATCH] Documents -d: in the compiler guide and hyperlinks
 assert/defined.

---
 doc/nimrodc.txt | 12 ++++++++++++
 lib/system.nim  | 20 +++++++++++++++++---
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt
index e4f1c41dca..fea1037dad 100644
--- a/doc/nimrodc.txt
+++ b/doc/nimrodc.txt
@@ -87,6 +87,18 @@ Level  Description
        for compiler developers.
 =====  ============================================
 
+
+Compile time symbols
+--------------------
+
+Through the ``-d:x`` or ``--define:x`` switch you can define compile time
+symbols for conditional compilation. The defined switches can be checked in
+source code with the `when statement <manual.html#when-statement>`_ and
+`defined proc <system.html#defined>`_. The typical use of this switch is to
+enable builds in release mode (``-d:release``) where certain safety checks are
+omitted for better performance. Another common use is the ``-d:ssl`` switch to
+activate `SSL sockets <sockets.html>`_.
+
 
 Configuration files
 -------------------
diff --git a/lib/system.nim b/lib/system.nim
index 4a4872b98e..2f24f68b1e 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.}
@@ -2812,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