Add Documentation (#13811)

* Add more Docs and runnableExamples

7 files changed, 110 insertions, 15 deletions

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