Add Documentation (#13811)

* Add more Docs and runnableExamples

12 files changed, 135 insertions, 19 deletions

diff --git a/lib/impure/rdstdin.nim b/lib/impure/rdstdin.nim
index 4c36afe6e..670b5ab72 100644
--- a/lib/impure/rdstdin.nim
+++ b/lib/impure/rdstdin.nim
@@ -12,7 +12,14 @@
 ## (e.g. you can navigate with the arrow keys). On Windows ``system.readLine``
 ## is used. This suffices because Windows' console already provides the
 ## wanted functionality.
-
+##
+## **Examples:**
+##
+## .. code-block:: nim
+##   echo readLineFromStdin("Is Nim awesome? (Y/n):")
+##   var userResponse: string
+##   doAssert readLineFromStdin("How are you?:", line = userResponse)
+##   echo userResponse
 {.deadCodeElim: on.}  # dce option deprecated
 
 when defined(Windows):
@@ -66,4 +73,3 @@ else:
       historyAdd(buffer)
     linenoise.free(buffer)
     result = true
-
diff --git a/lib/posix/posix_utils.nim b/lib/posix/posix_utils.nim
index 20a71971a..5600a5db5 100644
--- a/lib/posix/posix_utils.nim
+++ b/lib/posix/posix_utils.nim
@@ -98,4 +98,3 @@ proc mkdtemp*(prefix: string): string =
   if mkdtemp(tmpl) == nil:
     raise newException(OSError, $strerror(errno))
   return $tmpl
-
diff --git a/lib/pure/browsers.nim b/lib/pure/browsers.nim
index ee302f950..81a231aa2 100644
--- a/lib/pure/browsers.nim
+++ b/lib/pure/browsers.nim
@@ -33,6 +33,9 @@ proc openDefaultBrowser*(url: string) =
   ## used to determine the default browser to use.
   ##
   ## This proc doesn't raise an exception on error, beware.
+  ##
+  ## .. code-block:: nim
+  ##   block: openDefaultBrowser("https://nim-lang.org")
   when defined(windows):
     var o = newWideCString(osOpenCmd)
     var u = newWideCString(url)
diff --git a/lib/pure/collections/critbits.nim b/lib/pure/collections/critbits.nim
index a28bb447c..250042e7a 100644
--- a/lib/pure/collections/critbits.nim
+++ b/lib/pure/collections/critbits.nim
@@ -324,6 +324,32 @@ proc `$`*[T](c: CritBitTree[T]): string =
         result.addQuoted(val)
     result.add("}")
 
+
+runnableExamples:
+  static:
+    block:
+      var critbitAsSet: CritBitTree[void]
+      doAssert critbitAsSet.len == 0
+      incl critbitAsSet, "kitten"
+      doAssert critbitAsSet.len == 1
+      incl critbitAsSet, "puppy"
+      doAssert critbitAsSet.len == 2
+      incl critbitAsSet, "kitten"
+      doAssert critbitAsSet.len == 2
+      incl critbitAsSet, ""
+      doAssert critbitAsSet.len == 3
+  block:
+    var critbitAsDict: CritBitTree[int]
+    critbitAsDict["key"] = 42
+    doAssert critbitAsDict["key"] == 42
+    critbitAsDict["key"] = 0
+    doAssert critbitAsDict["key"] == 0
+    critbitAsDict["key"] = -int.high
+    doAssert critbitAsDict["key"] == -int.high
+    critbitAsDict["key"] = int.high
+    doAssert critbitAsDict["key"] == int.high
+
+
 when isMainModule:
   import sequtils
 
diff --git a/lib/pure/concurrency/cpuinfo.nim b/lib/pure/concurrency/cpuinfo.nim
index 515d7e2da..51f80b103 100644
--- a/lib/pure/concurrency/cpuinfo.nim
+++ b/lib/pure/concurrency/cpuinfo.nim
@@ -49,6 +49,9 @@ when defined(haiku):
 proc countProcessors*(): int {.rtl, extern: "ncpi$1".} =
   ## returns the number of the processors/cores the machine has.
   ## Returns 0 if it cannot be detected.
+  ##
+  ## .. code-block:: nim
+  ##   block: doAssert countProcessors() >= 0
   when defined(windows):
     type
       SYSTEM_INFO {.final, pure.} = object
diff --git a/lib/pure/mersenne.nim b/lib/pure/mersenne.nim
index a2b8914d9..812893508 100644
--- a/lib/pure/mersenne.nim
+++ b/lib/pure/mersenne.nim
@@ -39,6 +39,14 @@ proc getNum*(m: var MersenneTwister): uint32 =
   result = result xor ((result shl 15'u32) and 0xefc60000'u32)
   result = result xor (result shr 18'u32)
 
+
+runnableExamples:
+  static:
+    block:
+      var rando: MersenneTwister = newMersenneTwister(uint32.high)  ## Must be "var".
+      doAssert rando.getNum() != rando.getNum()  ## Pseudo random number. Works at compile-time.
+
+
 # Test
 when not defined(testing) and isMainModule:
   var mt = newMersenneTwister(2525)
diff --git a/lib/pure/mimetypes.nim b/lib/pure/mimetypes.nim
index f3f6e9324..3bbd0d243 100644
--- a/lib/pure/mimetypes.nim
+++ b/lib/pure/mimetypes.nim
@@ -1917,18 +1917,20 @@ func register*(mimedb: var MimeDB, ext: string, mimetype: string) =
   mimedb.mimes[ext.toLowerAscii()] = mimetype.toLowerAscii()
 
 runnableExamples:
-  var m = newMimetypes()
-  assert m.getMimetype("mp4") == "video/mp4"
-  assert m.getExt("text/html") == "html"
-  ## Values can be uppercase too.
-  assert m.getMimetype("MP4") == "video/mp4"
-  assert m.getExt("TEXT/HTML") == "html"
-  ## If values are invalid then ``default`` is returned.
-  assert m.getMimetype("INVALID") == "text/plain"
-  assert m.getExt("INVALID/NONEXISTENT") == "txt"
-  assert m.getMimetype("") == "text/plain"
-  assert m.getExt("") == "txt"
-  ## Register new Mimetypes.
-  m.register(ext = "fakext", mimetype = "text/fakelang")
-  assert m.getMimetype("fakext") == "text/fakelang"
-  assert m.getMimetype("FaKeXT") == "text/fakelang"
+  static:
+    block:
+      var m = newMimetypes()
+      doAssert m.getMimetype("mp4") == "video/mp4"
+      doAssert m.getExt("text/html") == "html"
+      ## Values can be uppercase too.
+      doAssert m.getMimetype("MP4") == "video/mp4"
+      doAssert m.getExt("TEXT/HTML") == "html"
+      ## If values are invalid then ``default`` is returned.
+      doAssert m.getMimetype("INVALID") == "text/plain"
+      doAssert m.getExt("INVALID/NONEXISTENT") == "txt"
+      doAssert m.getMimetype("") == "text/plain"
+      doAssert m.getExt("") == "txt"
+      ## Register new Mimetypes.
+      m.register(ext = "fakext", mimetype = "text/fakelang")
+      doAssert m.getMimetype("fakext") == "text/fakelang"
+      doAssert m.getMimetype("FaKeXT") == "text/fakelang"
diff --git a/lib/pure/punycode.nim b/lib/pure/punycode.nim
index ce80a37fa..fc80fabfd 100644
--- a/lib/pure/punycode.nim
+++ b/lib/pure/punycode.nim
@@ -171,6 +171,43 @@ proc decode*(encoded: string): string {.raises: [PunyError].} =
     insert(result, $Rune(n), i)
     inc i
 
+
+runnableExamples:
+  static:
+    block:
+      doAssert encode("") == ""
+      doAssert encode("a") == "a-"
+      doAssert encode("A") == "A-"
+      doAssert encode("3") == "3-"
+      doAssert encode("-") == "--"
+      doAssert encode("--") == "---"
+      doAssert encode("abc") == "abc-"
+      doAssert encode("London") == "London-"
+      doAssert encode("Lloyd-Atkinson") == "Lloyd-Atkinson-"
+      doAssert encode("This has spaces") == "This has spaces-"
+      doAssert encode("ü") == "tda"
+      doAssert encode("München") == "Mnchen-3ya"
+      doAssert encode("Mnchen-3ya") == "Mnchen-3ya-"
+      doAssert encode("München-Ost") == "Mnchen-Ost-9db"
+      doAssert encode("Bahnhof München-Ost") == "Bahnhof Mnchen-Ost-u6b"
+    block:
+      doAssert decode("") == ""
+      doAssert decode("a-") ==  "a"
+      doAssert decode("A-") == "A"
+      doAssert decode("3-") == "3"
+      doAssert decode("--") == "-"
+      doAssert decode("---") == "--"
+      doAssert decode("abc-") == "abc"
+      doAssert decode("London-") == "London"
+      doAssert decode("Lloyd-Atkinson-") == "Lloyd-Atkinson"
+      doAssert decode("This has spaces-") == "This has spaces"
+      doAssert decode("tda") == "ü"
+      doAssert decode("Mnchen-3ya") == "München"
+      doAssert decode("Mnchen-3ya-") == "Mnchen-3ya"
+      doAssert decode("Mnchen-Ost-9db") == "München-Ost"
+      doAssert decode("Bahnhof Mnchen-Ost-u6b") == "Bahnhof München-Ost"
+
+
 when isMainModule:
   assert(decode(encode("", "bücher")) == "bücher")
   assert(decode(encode("münchen")) == "münchen")
diff --git a/lib/pure/stats.nim b/lib/pure/stats.nim
index d62276da9..ac48d9eee 100644
--- a/lib/pure/stats.nim
+++ b/lib/pure/stats.nim
@@ -320,6 +320,22 @@ proc `+=`*(a: var RunningRegress, b: RunningRegress) =
 {.pop.}
 {.pop.}
 
+
+runnableExamples:
+  static:
+    block:
+      var statistics: RunningStat  ## Must be "var"
+      statistics.push(@[1.0, 2.0, 1.0, 4.0, 1.0, 4.0, 1.0, 2.0])
+      doAssert statistics.n == 8
+      doAssert statistics.mean() is SomeFloat
+      doAssert statistics.variance() is SomeFloat
+      doAssert statistics.varianceS() is SomeFloat
+      doAssert statistics.skewness() is SomeFloat
+      doAssert statistics.skewnessS() is SomeFloat
+      doAssert statistics.kurtosis() is SomeFloat
+      doAssert statistics.kurtosisS() is SomeFloat
+
+
 when isMainModule:
   proc clean(x: float): float =
     result = round(1.0e8*x).float * 1.0e-8
diff --git a/lib/std/editdistance.nim b/lib/std/editdistance.nim
index 0cb5edc9b..f365d4ab2 100644
--- a/lib/std/editdistance.nim
+++ b/lib/std/editdistance.nim
@@ -13,10 +13,11 @@
 import unicode
 
 proc editDistance*(a, b: string): int {.noSideEffect.} =
-  ## Returns the unicode-rune edit distance between ``a`` and ``b``.
+  ## Returns the **unicode-rune** edit distance between ``a`` and ``b``.
   ##
   ## This uses the `Levenshtein`:idx: distance algorithm with only a linear
   ## memory overhead.
+  runnableExamples: static: doAssert editdistance("Kitten", "Bitten") == 1
   if len(a) > len(b):
     # make ``b`` the longer string
     return editDistance(b, a)
@@ -181,6 +182,7 @@ proc editDistanceAscii*(a, b: string): int {.noSideEffect.} =
   ##
   ## This uses the `Levenshtein`:idx: distance algorithm with only a linear
   ## memory overhead.
+  runnableExamples: static: doAssert editDistanceAscii("Kitten", "Bitten") == 1
   var len1 = a.len
   var len2 = b.len
   if len1 > len2:
diff --git a/lib/std/sums.nim b/lib/std/sums.nim
index dc9d8d507..a48360180 100644
--- a/lib/std/sums.nim
+++ b/lib/std/sums.nim
@@ -54,6 +54,14 @@ func sumPairs*[T](x: openArray[T]): T =
   if n == 0: T(0) else: sumPairwise(x, 0, n)
 
 
+runnableExamples:
+  static:
+    block:
+      const data = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+      doAssert sumKbn(data) == 45
+      doAssert sumPairs(data) == 45
+
+
 when isMainModule:
   from math import pow
 
diff --git a/lib/system/assertions.nim b/lib/system/assertions.nim
index 5eb700f4c..13836a540 100644
--- a/lib/system/assertions.nim
+++ b/lib/system/assertions.nim
@@ -48,11 +48,17 @@ template assert*(cond: untyped, msg = "") =
   ## The compiler may not generate any code at all for ``assert`` if it is
   ## advised to do so through the ``-d:danger`` or ``--assertions:off``
   ## `command line switches <nimc.html#compiler-usage-command-line-switches>`_.
+  ##
+  ## .. code-block:: nim
+  ##   static: assert 1 == 9, "This works when not built with -d:danger or --assertions:off"
   const expr = astToStr(cond)
   assertImpl(cond, msg, expr, compileOption("assertions"))
 
 template doAssert*(cond: untyped, msg = "") =
   ## Similar to ``assert`` but is always turned on regardless of ``--assertions``.
+  ##
+  ## .. code-block:: nim
+  ##   static: assert 1 == 9, "This works when built with/without -d:danger or --assertions:off"
   const expr = astToStr(cond)
   assertImpl(cond, msg, expr, true)