Added documentation for when nimvm statement.

1 files changed, 31 insertions, 2 deletions

diff --git a/doc/manual/stmts.txt b/doc/manual/stmts.txt
index 32c01dccb..3fc950b4b 100644
--- a/doc/manual/stmts.txt
+++ b/doc/manual/stmts.txt
@@ -176,8 +176,8 @@ The rules for compile-time computability are:
 1. Literals are compile-time computable.
 2. Type conversions are compile-time computable.
 3. Procedure calls of the form ``p(X)`` are compile-time computable if
-   ``p`` is a proc without side-effects (see the `noSideEffect pragma 
-   <#pragmas-nosideeffect-pragma>`_ for details) and if ``X`` is a 
+   ``p`` is a proc without side-effects (see the `noSideEffect pragma
+   <#pragmas-nosideeffect-pragma>`_ for details) and if ``X`` is a
    (possibly empty) list of compile-time computable arguments.
 
 
@@ -329,6 +329,35 @@ The ``when`` statement enables conditional compilation techniques. As
 a special syntactic extension, the ``when`` construct is also available
 within ``object`` definitions.
 
+When nimvm statement
+---------------------
+``nimvm`` is a special symbol, that may be used as expression of ``when nimvm``
+statement to differentiate execution path between runtime and compile time.
+
+Example:
+
+.. code-block:: nim
+  proc someProcThatMayRunInCompileTime(): bool =
+    when nimvm:
+      # This code runs in compile time
+      result = true
+    else:
+      # This code runs in runtime
+      result = false
+  const ctValue = someProcThatMayRunInCompileTime()
+  let rtValue = someProcThatMayRunInCompileTime()
+  assert(ctValue == true)
+  assert(rtValue == false)
+
+``when nimvm`` statement must meet the following requirements:
+
+* Its expression must always be ``nimvm``. More complex expressions are not
+  allowed.
+* It must not contain ``elif`` branches.
+* It must contain ``else`` branch.
+* Code in branches must not affect semantics of the code that follows the
+  ``when nimvm`` statement. E.g. it must not define symbols that are used in
+  the following code.
 
 Return statement
 ----------------