Improve documentation for random (#17015)

* Improve documentation for random

Use runnableExamples
Minor changes

* Apply suggestions

Remove echo
Use RNG in more places

* Fix skipRandomNumbers example

1 files changed, 168 insertions, 185 deletions

diff --git a/lib/pure/random.nim b/lib/pure/random.nim
index 63672b496..f7f0f457d 100644
--- a/lib/pure/random.nim
+++ b/lib/pure/random.nim
@@ -7,9 +7,9 @@
 #    distribution, for details about the copyright.
 #
 
-## Nim's standard random number generator.
+## Nim's standard random number generator (RNG).
 ##
-## Its implementation is based on the ``xoroshiro128+``
+## Its implementation is based on the `xoroshiro128+`
 ## (xor/rotate/shift/rotate) library.
 ## * More information: http://xoroshiro.di.unimi.it
 ## * C implementation: http://xoroshiro.di.unimi.it/xoroshiro128plus.c
@@ -19,70 +19,63 @@
 ## Basic usage
 ## ===========
 ##
-## To get started, here are some examples:
-##
-## .. code-block::
-##
-##   import random
-##
-##   # Call randomize() once to initialize the default random number generator
-##   # If this is not called, the same results will occur every time these
-##   # examples are run
-##   randomize()
-##
-##   # Pick a number between 0 and 100
-##   let num = rand(100)
-##   echo num
-##
-##   # Roll a six-sided die
-##   let roll = rand(1..6)
-##   echo roll
-##
-##   # Pick a marble from a bag
-##   let marbles = ["red", "blue", "green", "yellow", "purple"]
-##   let pick = sample(marbles)
-##   echo pick
-##
-##   # Shuffle some cards
-##   var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
-##   shuffle(cards)
-##   echo cards
-##
-## These examples all use the default random number generator. The
-## `Rand type<#Rand>`_ represents the state of a random number generator.
+runnableExamples:
+  # Call randomize() once to initialize the default random number generator.
+  # If this is not called, the same results will occur every time these
+  # examples are run.
+  randomize()
+
+  # Pick a number in 0..100.
+  let num = rand(100)
+  doAssert num in 0..100
+
+  # Roll a six-sided die.
+  let roll = rand(1..6)
+  doAssert roll in 1..6
+
+  # Pick a marble from a bag.
+  let marbles = ["red", "blue", "green", "yellow", "purple"]
+  let pick = sample(marbles)
+  doAssert pick in marbles
+
+  # Shuffle some cards.
+  var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
+  shuffle(cards)
+  doAssert cards.len == 5
+
+## These examples all use the default RNG. The
+## `Rand type <#Rand>`_ represents the state of an RNG.
 ## For convenience, this module contains a default Rand state that corresponds
-## to the default random number generator. Most procs in this module which do
+## to the default RNG. Most procs in this module which do
 ## not take in a Rand parameter, including those called in the above examples,
 ## use the default generator. Those procs are **not** thread-safe.
 ##
 ## Note that the default generator always starts in the same state.
-## The `randomize proc<#randomize>`_ can be called to initialize the default
+## The `randomize proc <#randomize>`_ can be called to initialize the default
 ## generator with a seed based on the current time, and it only needs to be
 ## called once before the first usage of procs from this module. If
-## ``randomize`` is not called, then the default generator will always produce
+## `randomize` is not called, the default generator will always produce
 ## the same results.
 ##
-## Generators that are independent of the default one can be created with the
-## `initRand proc<#initRand,int64>`_.
+## RNGs that are independent of the default one can be created with the
+## `initRand proc <#initRand,int64>`_.
 ##
 ## Again, it is important to remember that this module must **not** be used for
 ## cryptographic applications.
 ##
 ## See also
 ## ========
-## * `std/sysrand module<sysrand.html>`_ for cryptographically secure pseudorandom number generator
-## * `math module<math.html>`_ for basic math routines
-## * `mersenne module<mersenne.html>`_ for the Mersenne Twister random number
-##   generator
-## * `stats module<stats.html>`_ for statistical analysis
-## * `list of cryptographic and hashing modules
-##   <lib.html#pure-libraries-hashing>`_
+## * `std/sysrand module <sysrand.html>`_ for a cryptographically secure pseudorandom number generator
+## * `mersenne module <mersenne.html>`_ for the Mersenne Twister random number generator
+## * `math module <math.html>`_ for basic math routines
+## * `stats module <stats.html>`_ for statistical analysis
+## * `list of cryptographic and hashing modules <lib.html#pure-libraries-hashing>`_
 ##   in the standard library
 
-import algorithm, math
+import std/[algorithm, math]
 import std/private/since
 
-include "system/inclrtl"
+include system/inclrtl
 {.push debugger: off.}
 
 when defined(js):
@@ -97,12 +90,12 @@ else:
 type
   Rand* = object ## State of a random number generator.
                  ##
-                 ## Create a new Rand state using the `initRand proc<#initRand,int64>`_.
+                 ## Create a new Rand state using the `initRand proc <#initRand,int64>`_.
                  ##
                  ## The module contains a default Rand state for convenience.
-                 ## It corresponds to the default random number generator's state.
+                 ## It corresponds to the default RNG's state.
                  ## The default Rand state always starts with the same values, but the
-                 ## `randomize proc<#randomize>`_ can be used to seed the default generator
+                 ## `randomize proc <#randomize>`_ can be used to seed the default generator
                  ## with a value based on the current time.
                  ##
                  ## Many procs have two variations: one that takes in a Rand parameter and
@@ -130,9 +123,9 @@ proc rotl(x, k: Ui): Ui =
   result = (x shl k) or (x shr (Ui(64) - k))
 
 proc next*(r: var Rand): uint64 =
-  ## Computes a random ``uint64`` number using the given state.
+  ## Computes a random `uint64` number using the given state.
   ##
-  ## See also:
+  ## **See also:**
   ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer between zero and
   ##   a given upper bound
   ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
@@ -145,6 +138,7 @@ proc next*(r: var Rand): uint64 =
     doAssert r.next() == 138_744_656_611_299'u64
     doAssert r.next() == 979_810_537_855_049_344'u64
     doAssert r.next() == 3_628_232_584_225_300_704'u64
+
   let s0 = r.a0
   var s1 = r.a1
   result = s0 + s1
@@ -155,12 +149,12 @@ proc next*(r: var Rand): uint64 =
 proc skipRandomNumbers*(s: var Rand) =
   ## The jump function for the generator.
   ##
-  ## This proc is equivalent to 2^64 calls to `next<#next,Rand>`_, and it can
-  ## be used to generate 2^64 non-overlapping subsequences for parallel
+  ## This proc is equivalent to `2^64` calls to `next <#next,Rand>`_, and it can
+  ## be used to generate `2^64` non-overlapping subsequences for parallel
   ## computations.
   ##
   ## When multiple threads are generating random numbers, each thread must
-  ## own the `Rand<#Rand>`_ state it is using so that the thread can safely
+  ## own the `Rand <#Rand>`_ state it is using so that the thread can safely
   ## obtain random numbers. However, if each thread creates its own Rand state,
   ## the subsequences of random numbers that each thread generates may overlap,
   ## even if the provided seeds are unique. This is more likely to happen as the
@@ -171,34 +165,30 @@ proc skipRandomNumbers*(s: var Rand) =
   ## Rand state to a thread, call this proc before passing it to the next one.
   ## By using the Rand state this way, the subsequences of random numbers
   ## generated in each thread will never overlap as long as no thread generates
-  ## more than 2^64 random numbers.
-  ##
-  ## The following example below demonstrates this pattern:
-  ##
-  ## .. code-block::
-  ##   # Compile this example with --threads:on
-  ##   import random
-  ##   import threadpool
+  ## more than `2^64` random numbers.
   ##
-  ##   const spawns = 4
-  ##   const numbers = 100000
-  ##
-  ##   proc randomSum(rand: Rand): int =
-  ##     var r = rand
-  ##     for i in 1..numbers:
-  ##       result += rand(1..10)
-  ##
-  ##   var r = initRand(2019)
-  ##   var vals: array[spawns, FlowVar[int]]
-  ##   for val in vals.mitems:
-  ##     val = spawn(randomSum(r))
-  ##     r.skipRandomNumbers()
-  ##
-  ##   for val in vals:
-  ##     echo ^val
-  ##
-  ## See also:
+  ## **See also:**
   ## * `next proc<#next,Rand>`_
+  runnableExamples("--threads:on"):
+    import std/[random, threadpool]
+
+    const spawns = 4
+    const numbers = 100000
+
+    proc randomSum(r: Rand): int =
+      var r = r
+      for i in 1..numbers:
+        result += r.rand(0..10)
+
+    var r = initRand(2019)
+    var vals: array[spawns, FlowVar[int]]
+    for val in vals.mitems:
+      val = spawn randomSum(r)
+      r.skipRandomNumbers()
+
+    for val in vals:
+      doAssert abs(^val - numbers * 5) / numbers < 0.1
+
   when defined(js):
     const helper = [0xbeac0467u32, 0xd86b048bu32]
   else:
@@ -218,9 +208,8 @@ proc skipRandomNumbers*(s: var Rand) =
 proc rand*(r: var Rand; max: Natural): int {.benign.} =
   ## Returns a random integer in the range `0..max` using the given state.
   ##
-  ## See also:
-  ## * `rand proc<#rand,int>`_ that returns an integer using the default
-  ##   random number generator
+  ## **See also:**
+  ## * `rand proc<#rand,int>`_ that returns an integer using the default RNG
   ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
   ## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
   ##   that accepts a slice
@@ -230,22 +219,22 @@ proc rand*(r: var Rand; max: Natural): int {.benign.} =
     doAssert r.rand(100) == 0
     doAssert r.rand(100) == 96
     doAssert r.rand(100) == 66
+
   if max == 0: return
   while true:
     let x = next(r)
     if x <= randMax - (randMax mod Ui(max)):
-      return int(x mod (uint64(max)+1u64))
+      return int(x mod (uint64(max) + 1u64))
 
 proc rand*(max: int): int {.benign.} =
   ## Returns a random integer in the range `0..max`.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the sequence of random
+  ## If `randomize <#randomize>`_ has not been called, the sequence of random
   ## numbers returned from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer using a
   ##   provided state
   ## * `rand proc<#rand,float>`_ that returns a float
@@ -257,23 +246,23 @@ proc rand*(max: int): int {.benign.} =
     doAssert rand(100) == 0
     doAssert rand(100) == 96
     doAssert rand(100) == 66
+
   rand(state, max)
 
 proc rand*(r: var Rand; max: range[0.0 .. high(float)]): float {.benign.} =
   ## Returns a random floating point number in the range `0.0..max`
   ## using the given state.
   ##
-  ## See also:
-  ## * `rand proc<#rand,float>`_ that returns a float using the default
-  ##   random number generator
+  ## **See also:**
+  ## * `rand proc<#rand,float>`_ that returns a float using the default RNG
   ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer
   ## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
   ##   that accepts a slice
   ## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type
   runnableExamples:
     var r = initRand(234)
-    let f = r.rand(1.0)
-    ## f = 8.717181376738381e-07
+    let f = r.rand(1.0) # 8.717181376738381e-07
+
   let x = next(r)
   when defined(js):
     result = (float(x) / float(high(uint32))) * max
@@ -284,13 +273,12 @@ proc rand*(r: var Rand; max: range[0.0 .. high(float)]): float {.benign.} =
 proc rand*(max: float): float {.benign.} =
   ## Returns a random floating point number in the range `0.0..max`.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the sequence of random
+  ## If `randomize <#randomize>`_ has not been called, the sequence of random
   ## numbers returned from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `rand proc<#rand,Rand,range[]>`_ that returns a float using a
   ##   provided state
   ## * `rand proc<#rand,int>`_ that returns an integer
@@ -299,8 +287,8 @@ proc rand*(max: float): float {.benign.} =
   ## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type
   runnableExamples:
     randomize(234)
-    let f = rand(1.0)
-    ## f = 8.717181376738381e-07
+    let f = rand(1.0) # 8.717181376738381e-07
+
   rand(state, max)
 
 proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T =
@@ -309,9 +297,9 @@ proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T =
   ##
   ## Allowed types for `T` are integers, floats, and enums without holes.
   ##
-  ## See also:
+  ## **See also:**
   ## * `rand proc<#rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
-  ##   that accepts a slice and uses the default random number generator
+  ##   that accepts a slice and uses the default RNG
   ## * `rand proc<#rand,Rand,Natural>`_ that returns an integer
   ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
   ## * `rand proc<#rand,typedesc[T]>`_ that accepts an integer or range type
@@ -320,8 +308,8 @@ proc rand*[T: Ordinal or SomeFloat](r: var Rand; x: HSlice[T, T]): T =
     doAssert r.rand(1..6) == 4
     doAssert r.rand(1..6) == 4
     doAssert r.rand(1..6) == 6
-    let f = r.rand(-1.0 .. 1.0)
-    ## f = 0.8741183448756229
+    let f = r.rand(-1.0 .. 1.0) # 0.8741183448756229
+
   when T is SomeFloat:
     result = rand(r, x.b - x.a) + x.a
   else: # Integers and Enum types
@@ -332,13 +320,12 @@ proc rand*[T: Ordinal or SomeFloat](x: HSlice[T, T]): T =
   ##
   ## Allowed types for `T` are integers, floats, and enums without holes.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the sequence of random
+  ## If `randomize <#randomize>`_ has not been called, the sequence of random
   ## numbers returned from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `rand proc<#rand,Rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
   ##   that accepts a slice and uses a provided state
   ## * `rand proc<#rand,int>`_ that returns an integer
@@ -349,18 +336,18 @@ proc rand*[T: Ordinal or SomeFloat](x: HSlice[T, T]): T =
     doAssert rand(1..6) == 4
     doAssert rand(1..6) == 4
     doAssert rand(1..6) == 6
+
   result = rand(state, x)
 
 proc rand*[T: SomeInteger](t: typedesc[T]): T =
   ## Returns a random integer in the range `low(T)..high(T)`.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the sequence of random
+  ## If `randomize <#randomize>`_ has not been called, the sequence of random
   ## numbers returned from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `rand proc<#rand,int>`_ that returns an integer
   ## * `rand proc<#rand,float>`_ that returns a floating point number
   ## * `rand proc<#rand,HSlice[T: Ordinal or float or float32 or float64,T: Ordinal or float or float32 or float64]>`_
@@ -376,18 +363,18 @@ proc rand*[T: SomeInteger](t: typedesc[T]): T =
     doAssert rand(range[1..16]) == 11
     doAssert rand(range[1..16]) == 4
     doAssert rand(range[1..16]) == 16
+
   when T is range:
     result = rand(state, low(T)..high(T))
   else:
     result = cast[T](state.next)
 
 proc sample*[T](r: var Rand; s: set[T]): T =
-  ## Returns a random element from the set ``s`` using the given state.
+  ## Returns a random element from the set `s` using the given state.
   ##
-  ## See also:
-  ## * `sample proc<#sample,set[T]>`_ that uses the default random number
-  ##   generator
-  ## * `sample proc<#sample,Rand,openArray[T]>`_ for openarrays
+  ## **See also:**
+  ## * `sample proc<#sample,set[T]>`_ that uses the default RNG
+  ## * `sample proc<#sample,Rand,openArray[T]>`_ for `openArray`s
   ## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that uses a
   ##   cumulative distribution function
   runnableExamples:
@@ -396,6 +383,7 @@ proc sample*[T](r: var Rand; s: set[T]): T =
     doAssert r.sample(s) == 5
     doAssert r.sample(s) == 7
     doAssert r.sample(s) == 1
+
   assert card(s) != 0
   var i = rand(r, card(s) - 1)
   for e in s:
@@ -403,17 +391,16 @@ proc sample*[T](r: var Rand; s: set[T]): T =
     dec(i)
 
 proc sample*[T](s: set[T]): T =
-  ## Returns a random element from the set ``s``.
+  ## Returns a random element from the set `s`.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the order of outcomes
+  ## If `randomize <#randomize>`_ has not been called, the order of outcomes
   ## from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `sample proc<#sample,Rand,set[T]>`_ that uses a provided state
-  ## * `sample proc<#sample,openArray[T]>`_ for openarrays
+  ## * `sample proc<#sample,openArray[T]>`_ for `openArray`s
   ## * `sample proc<#sample,openArray[T],openArray[U]>`_ that uses a
   ##   cumulative distribution function
   runnableExamples:
@@ -422,14 +409,14 @@ proc sample*[T](s: set[T]): T =
     doAssert sample(s) == 5
     doAssert sample(s) == 7
     doAssert sample(s) == 1
+
   sample(state, s)
 
 proc sample*[T](r: var Rand; a: openArray[T]): T =
-  ## Returns a random element from ``a`` using the given state.
+  ## Returns a random element from `a` using the given state.
   ##
-  ## See also:
-  ## * `sample proc<#sample,openArray[T]>`_ that uses the default
-  ##   random number generator
+  ## **See also:**
+  ## * `sample proc<#sample,openArray[T]>`_ that uses the default RNG
   ## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that uses a
   ##   cumulative distribution function
   ## * `sample proc<#sample,Rand,set[T]>`_ for sets
@@ -439,18 +426,18 @@ proc sample*[T](r: var Rand; a: openArray[T]): T =
     doAssert r.sample(marbles) == "blue"
     doAssert r.sample(marbles) == "yellow"
     doAssert r.sample(marbles) == "red"
+
   result = a[r.rand(a.low..a.high)]
 
 proc sample*[T](a: openArray[T]): T =
-  ## Returns a random element from ``a``.
+  ## Returns a random element from `a`.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the order of outcomes
+  ## If `randomize <#randomize>`_ has not been called, the order of outcomes
   ## from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `sample proc<#sample,Rand,openArray[T]>`_ that uses a provided state
   ## * `sample proc<#sample,openArray[T],openArray[U]>`_ that uses a
   ##   cumulative distribution function
@@ -461,28 +448,29 @@ proc sample*[T](a: openArray[T]): T =
     doAssert sample(marbles) == "blue"
     doAssert sample(marbles) == "yellow"
     doAssert sample(marbles) == "red"
+
   result = a[rand(a.low..a.high)]
 
 proc sample*[T, U](r: var Rand; a: openArray[T]; cdf: openArray[U]): T =
-  ## Returns an element from ``a`` using a cumulative distribution function
+  ## Returns an element from `a` using a cumulative distribution function
   ## (CDF) and the given state.
   ##
-  ## The ``cdf`` argument does not have to be normalized, and it could contain
-  ## any type of elements that can be converted to a ``float``. It must be
-  ## the same length as ``a``. Each element in ``cdf`` should be greater than
+  ## The `cdf` argument does not have to be normalized, and it could contain
+  ## any type of elements that can be converted to a `float`. It must be
+  ## the same length as `a`. Each element in `cdf` should be greater than
   ## or equal to the previous element.
   ##
   ## The outcome of the `cumsum<math.html#cumsum,openArray[T]>`_ proc and the
   ## return value of the `cumsummed<math.html#cumsummed,openArray[T]>`_ proc,
-  ## which are both in the math module, can be used as the ``cdf`` argument.
+  ## which are both in the math module, can be used as the `cdf` argument.
   ##
-  ## See also:
+  ## **See also:**
   ## * `sample proc<#sample,openArray[T],openArray[U]>`_ that also utilizes
-  ##   a CDF but uses the default random number generator
+  ##   a CDF but uses the default RNG
   ## * `sample proc<#sample,Rand,openArray[T]>`_ that does not use a CDF
   ## * `sample proc<#sample,Rand,set[T]>`_ for sets
   runnableExamples:
-    from math import cumsummed
+    from std/math import cumsummed
 
     let marbles = ["red", "blue", "green", "yellow", "purple"]
     let count = [1, 6, 8, 3, 4]
@@ -491,35 +479,34 @@ proc sample*[T, U](r: var Rand; a: openArray[T]; cdf: openArray[U]): T =
     doAssert r.sample(marbles, cdf) == "red"
     doAssert r.sample(marbles, cdf) == "green"
     doAssert r.sample(marbles, cdf) == "blue"
+
   assert(cdf.len == a.len) # Two basic sanity checks.
   assert(float(cdf[^1]) > 0.0)
-  #While we could check cdf[i-1] <= cdf[i] for i in 1..cdf.len, that could get
-  #awfully expensive even in debugging modes.
+  # While we could check cdf[i-1] <= cdf[i] for i in 1..cdf.len, that could get
+  # awfully expensive even in debugging modes.
   let u = r.rand(float(cdf[^1]))
   a[cdf.upperBound(U(u))]
 
 proc sample*[T, U](a: openArray[T]; cdf: openArray[U]): T =
-  ## Returns an element from ``a`` using a cumulative distribution function
+  ## Returns an element from `a` using a cumulative distribution function
   ## (CDF).
   ##
   ## This proc works similarly to
-  ## `sample[T, U](Rand, openArray[T], openArray[U])
-  ## <#sample,Rand,openArray[T],openArray[U]>`_.
+  ## `sample <#sample,Rand,openArray[T],openArray[U]>`_.
   ## See that proc's documentation for more details.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the order of outcomes
+  ## If `randomize <#randomize>`_ has not been called, the order of outcomes
   ## from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `sample proc<#sample,Rand,openArray[T],openArray[U]>`_ that also utilizes
   ##   a CDF but uses a provided state
   ## * `sample proc<#sample,openArray[T]>`_ that does not use a CDF
   ## * `sample proc<#sample,set[T]>`_ for sets
   runnableExamples:
-    from math import cumsummed
+    from std/math import cumsummed
 
     let marbles = ["red", "blue", "green", "yellow", "purple"]
     let count = [1, 6, 8, 3, 4]
@@ -528,14 +515,15 @@ proc sample*[T, U](a: openArray[T]; cdf: openArray[U]): T =
     doAssert sample(marbles, cdf) == "red"
     doAssert sample(marbles, cdf) == "green"
     doAssert sample(marbles, cdf) == "blue"
+
   state.sample(a, cdf)
 
 proc gauss*(r: var Rand; mu = 0.0; sigma = 1.0): float {.since: (1, 3).} =
   ## Returns a Gaussian random variate,
-  ## with mean ``mu`` and standard deviation ``sigma``
+  ## with mean `mu` and standard deviation `sigma`
   ## using the given state.
   # Ratio of uniforms method for normal
-  # http://www2.econ.osaka-u.ac.jp/~tanizaki/class/2013/econome3/13.pdf
+  # https://www2.econ.osaka-u.ac.jp/~tanizaki/class/2013/econome3/13.pdf
   const K = sqrt(2 / E)
   var
     a = 0.0
@@ -548,37 +536,34 @@ proc gauss*(r: var Rand; mu = 0.0; sigma = 1.0): float {.since: (1, 3).} =
 
 proc gauss*(mu = 0.0, sigma = 1.0): float {.since: (1, 3).} =
   ## Returns a Gaussian random variate,
-  ## with mean ``mu`` and standard deviation ``sigma``.
+  ## with mean `mu` and standard deviation `sigma`.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the order of outcomes
+  ## If `randomize <#randomize>`_ has not been called, the order of outcomes
   ## from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   result = gauss(state, mu, sigma)
 
 proc initRand*(seed: int64): Rand =
-  ## Initializes a new `Rand<#Rand>`_ state using the given seed.
+  ## Initializes a new `Rand <#Rand>`_ state using the given seed.
   ##
   ## `seed` must not be zero. Providing a specific seed will produce
   ## the same results for that seed each time.
   ##
-  ## The resulting state is independent of the default random number
-  ## generator's state.
+  ## The resulting state is independent of the default RNG's state.
   ##
-  ## See also:
+  ## **See also:**
   ## * `initRand proc<#initRand>`_ that uses the current time
-  ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default
-  ##   random number generator
-  ## * `randomize proc<#randomize>`_ that initializes the default random
-  ##   number generator using the current time
+  ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default RNG
+  ## * `randomize proc<#randomize>`_ that initializes the default RNG using the current time
   runnableExamples:
-    from times import getTime, toUnix, nanosecond
+    from std/times import getTime, toUnix, nanosecond
 
     var r1 = initRand(123)
 
     let now = getTime()
     var r2 = initRand(now.toUnix * 1_000_000_000 + now.nanosecond)
+
   doAssert seed != 0 # 0 causes `rand(int)` to always return 0 for example.
   result.a0 = Ui(seed shr 16)
   result.a1 = Ui(seed and 0xffff)
@@ -590,32 +575,33 @@ proc randomize*(seed: int64) {.benign.} =
   ## `seed` must not be zero. Providing a specific seed will produce
   ## the same results for that seed each time.
   ##
-  ## See also:
+  ## **See also:**
   ## * `initRand proc<#initRand,int64>`_ that initializes a Rand state
   ##   with a given seed
   ## * `randomize proc<#randomize>`_ that uses the current time instead
   ## * `initRand proc<#initRand>`_ that initializes a Rand state using
   ##   the current time
   runnableExamples:
-    from times import getTime, toUnix, nanosecond
+    from std/times import getTime, toUnix, nanosecond
 
     randomize(123)
 
     let now = getTime()
     randomize(now.toUnix * 1_000_000_000 + now.nanosecond)
+
   state = initRand(seed)
 
 proc shuffle*[T](r: var Rand; x: var openArray[T]) =
   ## Shuffles a sequence of elements in-place using the given state.
   ##
-  ## See also:
-  ## * `shuffle proc<#shuffle,openArray[T]>`_ that uses the default
-  ##   random number generator
+  ## **See also:**
+  ## * `shuffle proc<#shuffle,openArray[T]>`_ that uses the default RNG
   runnableExamples:
     var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
     var r = initRand(678)
     r.shuffle(cards)
     doAssert cards == ["King", "Ace", "Queen", "Ten", "Jack"]
+
   for i in countdown(x.high, 1):
     let j = r.rand(i)
     swap(x[i], x[j])
@@ -623,44 +609,42 @@ proc shuffle*[T](r: var Rand; x: var openArray[T]) =
 proc shuffle*[T](x: var openArray[T]) =
   ## Shuffles a sequence of elements in-place.
   ##
-  ## If `randomize<#randomize>`_ has not been called, the order of outcomes
+  ## If `randomize <#randomize>`_ has not been called, the order of outcomes
   ## from this proc will always be the same.
   ##
-  ## This proc uses the default random number generator. Thus, it is **not**
-  ## thread-safe.
+  ## This proc uses the default RNG. Thus, it is **not** thread-safe.
   ##
-  ## See also:
+  ## **See also:**
   ## * `shuffle proc<#shuffle,Rand,openArray[T]>`_ that uses a provided state
   runnableExamples:
     var cards = ["Ace", "King", "Queen", "Jack", "Ten"]
     randomize(678)
     shuffle(cards)
     doAssert cards == ["King", "Ace", "Queen", "Ten", "Jack"]
+
   shuffle(state, x)
 
 when not defined(nimscript) and not defined(standalone):
-  import times
-  
+  import std/times
+
   proc initRand(): Rand =
     ## Initializes a new Rand state with a seed based on the current time.
     ##
-    ## The resulting state is independent of the default random number generator's state.
+    ## The resulting state is independent of the default RNG's state.
     ##
     ## **Note:** Does not work for NimScript or the compile-time VM.
     ##
     ## See also:
     ## * `initRand proc<#initRand,int64>`_ that accepts a seed for a new Rand state
-    ## * `randomize proc<#randomize>`_ that initializes the default random
-    ##   number generator using the current time
-    ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default
-    ##   random number generator
+    ## * `randomize proc<#randomize>`_ that initializes the default RNG using the current time
+    ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default RNG
     when defined(js):
       let time = int64(times.epochTime() * 1000) and 0x7fff_ffff
       result = initRand(time)
     else:
       let now = times.getTime()
       result = initRand(convert(Seconds, Nanoseconds, now.toUnix) + now.nanosecond)
-  
+
   since (1, 5, 1):
     export initRand
 
@@ -669,12 +653,11 @@ when not defined(nimscript) and not defined(standalone):
     ## the current time.
     ##
     ## This proc only needs to be called once, and it should be called before
-    ## the first usage of procs from this module that use the default random
-    ## number generator.
+    ## the first usage of procs from this module that use the default RNG.
     ##
     ## **Note:** Does not work for NimScript or the compile-time VM.
     ##
-    ## See also:
+    ## **See also:**
     ## * `randomize proc<#randomize,int64>`_ that accepts a seed
     ## * `initRand proc<#initRand>`_ that initializes a Rand state using
     ##   the current time