even better docs

doc/nims.txt

@@ -40,7 +40,7 @@ NimScript as a build tool
 =========================
 
 The ``task`` template that the ``system`` module defines allows a NimScript
-file to be used as a build tool. The following exampled defines a
+file to be used as a build tool. The following example defines a
 task ``build`` that is an alias for the ``c`` command:
 
 .. code-block:: nim

lib/system/nimscript.nim

@@ -61,10 +61,17 @@ proc setCommand*(cmd: string) =
 proc cmpIgnoreStyle(a, b: string): int = builtin
 proc cmpIgnoreCase(a, b: string): int = builtin
 
-proc cmpic*(a, b: string): int = cmpIgnoreCase(a, b)
+proc cmpic*(a, b: string): int =
+  ## Compares `a` and `b` ignoring case.
+  cmpIgnoreCase(a, b)
 
-proc getEnv*(key: string): string = builtin
+proc getEnv*(key: string): string {.tags: [ReadIOEffect].} =
-proc existsEnv*(key: string): bool = builtin
+  ## Retrieves the environment variable of name `key`.
+  builtin
+
+proc existsEnv*(key: string): bool {.tags: [ReadIOEffect].} =
+  ## Checks for the existance of an environment variable named `key`.
+  builtin
 
 proc fileExists*(filename: string): bool {.tags: [ReadIOEffect].} =
   ## Checks if the file exists.
@@ -96,8 +103,13 @@ proc strip(s: string): string =
   while s[i] in {' ', '\c', '\L'}: inc i
   result = s.substr(i)
 
-template `--`*(key, val: untyped) = switch(astToStr(key), strip astToStr(val))
+template `--`*(key, val: untyped) =
-template `--`*(key: untyped) = switch(astToStr(key), "")
+  ## A shortcut for ``switch(astToStr(key), astToStr(val))``.
+  switch(astToStr(key), strip astToStr(val))
+
+template `--`*(key: untyped) =
+  ## A shortcut for ``switch(astToStr(key)``.
+  switch(astToStr(key), "")
 
 type
   ScriptMode* {.pure.} = enum ## Controls the behaviour of the script.
@@ -158,7 +170,8 @@ proc exec*(command: string) =
       raise newException(OSError, "FAILED: " & command)
     checkOsError()
 
-proc exec*(command: string, input: string, cache = "") =
+proc exec*(command: string, input: string, cache = "") {.
+  raises: [OSError], tags: [ExecIOEffect].} =
   ## Executes an external process.
   log "exec: " & command:
     echo staticExec(command, input, cache)