diff --git a/lib/system.nim b/lib/system.nim
index 65d5fa16a..a3cf5cde6 100644
--- a/lib/system.nim
+++ b/lib/system.nim
@@ -10,6 +10,7 @@
 ## The compiler depends on the System module to work properly and the System
 ## module depends on the compiler. Most of the routines listed here use
 ## special compiler magic.
+##
 ## Each module implicitly imports the System module; it must not be listed
 ## explicitly. Because of this there cannot be a user-defined module named
 ## ``system``.
@@ -22,93 +23,94 @@
 # in the global index as part of the previous header (Exception hierarchy).
 
 type
-  int* {.magic: Int.} ## default integer type; bitwidth depends on
-                      ## architecture, but is always the same as a pointer
-  int8* {.magic: Int8.} ## signed 8 bit integer type
-  int16* {.magic: Int16.} ## signed 16 bit integer type
-  int32* {.magic: Int32.} ## signed 32 bit integer type
-  int64* {.magic: Int64.} ## signed 64 bit integer type
-  uint* {.magic: UInt.} ## unsigned default integer type
-  uint8* {.magic: UInt8.} ## unsigned 8 bit integer type
-  uint16* {.magic: UInt16.} ## unsigned 16 bit integer type
-  uint32* {.magic: UInt32.} ## unsigned 32 bit integer type
-  uint64* {.magic: UInt64.} ## unsigned 64 bit integer type
-  float* {.magic: Float.} ## default floating point type
-  float32* {.magic: Float32.} ## 32 bit floating point type
-  float64* {.magic: Float.} ## 64 bit floating point type
+  int* {.magic: Int.}         ## Default integer type; bitwidth depends on
+                              ## architecture, but is always the same as a pointer.
+  int8* {.magic: Int8.}       ## Signed 8 bit integer type.
+  int16* {.magic: Int16.}     ## Signed 16 bit integer type.
+  int32* {.magic: Int32.}     ## Signed 32 bit integer type.
+  int64* {.magic: Int64.}     ## Signed 64 bit integer type.
+  uint* {.magic: UInt.}       ## Unsigned default integer type.
+  uint8* {.magic: UInt8.}     ## Unsigned 8 bit integer type.
+  uint16* {.magic: UInt16.}   ## Unsigned 16 bit integer type.
+  uint32* {.magic: UInt32.}   ## Unsigned 32 bit integer type.
+  uint64* {.magic: UInt64.}   ## Unsigned 64 bit integer type.
+  float* {.magic: Float.}     ## Default floating point type.
+  float32* {.magic: Float32.} ## 32 bit floating point type.
+  float64* {.magic: Float.}   ## 64 bit floating point type.
 
 # 'float64' is now an alias to 'float'; this solves many problems
 
 type # we need to start a new type section here, so that ``0`` can have a type
-  bool* {.magic: Bool.} = enum ## built-in boolean type
+  bool* {.magic: Bool.} = enum ## Built-in boolean type.
     false = 0, true = 1
 
 type
-  char* {.magic: Char.} ## built-in 8 bit character type (unsigned)
-  string* {.magic: String.} ## built-in string type
-  cstring* {.magic: Cstring.} ## built-in cstring (*compatible string*) type
-  pointer* {.magic: Pointer.} ## built-in pointer type, use the ``addr``
-                              ## operator to get a pointer to a variable
+  char* {.magic: Char.}         ## Built-in 8 bit character type (unsigned).
+  string* {.magic: String.}     ## Built-in string type.
+  cstring* {.magic: Cstring.}   ## Built-in cstring (*compatible string*) type.
+  pointer* {.magic: Pointer.}   ## Built-in pointer type, use the ``addr``
+                                ## operator to get a pointer to a variable.
 
-  typedesc* {.magic: TypeDesc.} ## meta type to denote a type description
+  typedesc* {.magic: TypeDesc.} ## Meta type to denote a type description.
 
 const
-  on* = true    ## alias for ``true``
-  off* = false  ## alias for ``false``
+  on* = true    ## Alias for ``true``.
+  off* = false  ## Alias for ``false``.
 
 {.push warning[GcMem]: off, warning[Uninit]: off.}
 {.push hints: off.}
 
 proc `or`*(a, b: typedesc): typedesc {.magic: "TypeTrait", noSideEffect.}
-  ## Constructs an `or` meta class
+  ## Constructs an `or` meta class.
 
 proc `and`*(a, b: typedesc): typedesc {.magic: "TypeTrait", noSideEffect.}
-  ## Constructs an `and` meta class
+  ## Constructs an `and` meta class.
 
 proc `not`*(a: typedesc): typedesc {.magic: "TypeTrait", noSideEffect.}
-  ## Constructs an `not` meta class
+  ## Constructs an `not` meta class.
 
 type
   Ordinal* {.magic: Ordinal.}[T] ## Generic ordinal type. Includes integer,
                                  ## bool, character, and enumeration types
                                  ## as well as their subtypes. Note `uint`
                                  ## and `uint64` are not ordinal types for
-                                 ## implementation reasons
-  `ptr`* {.magic: Pointer.}[T] ## built-in generic untraced pointer type
-  `ref`* {.magic: Pointer.}[T] ## built-in generic traced pointer type
+                                 ## implementation reasons.
+  `ptr`* {.magic: Pointer.}[T]   ## Built-in generic untraced pointer type.
+  `ref`* {.magic: Pointer.}[T]   ## Built-in generic traced pointer type.
 
   `nil` {.magic: "Nil".}
 
-  void* {.magic: "VoidType".}   ## meta type to denote the absence of any type
-  auto* {.magic: Expr.} ## meta type for automatic type determination
-  any* = distinct auto ## meta type for any supported type
-  untyped* {.magic: Expr.} ## meta type to denote an expression that
-                           ## is not resolved (for templates)
-  typed* {.magic: Stmt.}   ## meta type to denote an expression that
-                           ## is resolved (for templates)
+  void* {.magic: "VoidType".}    ## Meta type to denote the absence of any type.
+  auto* {.magic: Expr.}          ## Meta type for automatic type determination.
+  any* = distinct auto           ## Meta type for any supported type.
+  untyped* {.magic: Expr.}       ## Meta type to denote an expression that
+                                 ## is not resolved (for templates).
+  typed* {.magic: Stmt.}         ## Meta type to denote an expression that
+                                 ## is resolved (for templates).
 
   SomeSignedInt* = int|int8|int16|int32|int64
-    ## type class matching all signed integer types
+    ## Type class matching all signed integer types.
 
   SomeUnsignedInt* = uint|uint8|uint16|uint32|uint64
-    ## type class matching all unsigned integer types
+    ## Type class matching all unsigned integer types.
 
   SomeInteger* = SomeSignedInt|SomeUnsignedInt
-    ## type class matching all integer types
+    ## Type class matching all integer types.
 
   SomeOrdinal* = int|int8|int16|int32|int64|bool|enum|uint8|uint16|uint32
-    ## type class matching all ordinal types; however this includes enums with
+    ## Type class matching all ordinal types; however this includes enums with
     ## holes.
 
   SomeFloat* = float|float32|float64
-    ## type class matching all floating point number types
+    ## Type class matching all floating point number types.
 
   SomeNumber* = SomeInteger|SomeFloat
-    ## type class matching all number types
+    ## Type class matching all number types.
 
 proc defined*(x: untyped): bool {.magic: "Defined", noSideEffect, compileTime.}
   ## Special compile-time procedure that checks whether `x` is
   ## defined.
+  ##
   ## `x` is an external symbol introduced through the compiler's
   ## `-d:x switch <nimc.html#compile-time-symbols>`_ to enable build time
   ## conditionals:
@@ -130,6 +132,17 @@ when defined(nimHasRunnableExamples):
     ##   compiled and tested. The collected examples are
     ##   put into their own module to ensure the examples do not refer to
     ##   non-exported symbols.
+    ##
+    ## Usage:
+    ##
+    ## .. code-block:: Nim
+    ##   proc double(x: int): int =
+    ##     ## This proc doubles a number.
+    ##     runnableExamples:
+    ##       assert double(5) == 10
+    ##       assert double(21) == 42
+    ##
+    ##     result = 2 * x
 else:
   template runnableExamples*(body: untyped) =
     discard
@@ -137,6 +150,10 @@ else:
 proc declared*(x: untyped): bool {.magic: "Defined", noSideEffect, compileTime.}
   ## Special compile-time procedure that checks whether `x` is
   ## declared. `x` has to be an identifier or a qualified identifier.
+  ##
+  ## See also:
+  ## * `declaredInScope <#declaredInScope,untyped>`_
+  ##
   ## This can be used to check whether a library provides a certain
   ## feature or not:
   ##
@@ -154,43 +171,49 @@ proc declaredInScope*(x: untyped): bool {.
   ## declared in the current scope. `x` has to be an identifier.
 
 proc `addr`*[T](x: var T): ptr T {.magic: "Addr", noSideEffect.} =
-  ## Builtin 'addr' operator for taking the address of a memory location.
+  ## Builtin `addr` operator for taking the address of a memory location.
   ## Cannot be overloaded.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `unsafeAddr <#unsafeAddr,T>`_
+  ##
+  ## .. code-block:: Nim
   ##  var
   ##    buf: seq[char] = @['a','b','c']
-  ##    p: pointer = buf[1].addr
-  ##  echo cast[ptr char](p)[]    # b
+  ##    p = buf[1].addr
+  ##  echo p.repr # ref 0x7faa35c40059 --> 'b'
+  ##  echo p[]    # b
   discard
 
 proc unsafeAddr*[T](x: T): ptr T {.magic: "Addr", noSideEffect.} =
-  ## Builtin 'addr' operator for taking the address of a memory
-  ## location.  This works even for ``let`` variables or parameters
+  ## Builtin `addr` operator for taking the address of a memory
+  ## location. This works even for ``let`` variables or parameters
   ## for better interop with C and so it is considered even more
-  ## unsafe than the ordinary ``addr``.  When you use it to write a
-  ## wrapper for a C library, you should always check that the
-  ## original library does never write to data behind the pointer that
-  ## is returned from this procedure.
+  ## unsafe than the ordinary `addr <#addr,T>`_.
+  ##
+  ## **Note**: When you use it to write a wrapper for a C library, you should
+  ## always check that the original library does never write to data behind the
+  ## pointer that is returned from this procedure.
+  ##
   ## Cannot be overloaded.
   discard
 
 when defined(nimNewTypedesc):
   type
     `static`* {.magic: "Static".}[T]
-      ## meta type representing all values that can be evaluated at compile-time.
+      ## Meta type representing all values that can be evaluated at compile-time.
       ##
       ## The type coercion ``static(x)`` can be used to force the compile-time
       ## evaluation of the given expression ``x``.
 
     `type`* {.magic: "Type".}[T]
-      ## meta type representing the type of all type values.
+      ## Meta type representing the type of all type values.
       ##
       ## The coercion ``type(x)`` can be used to obtain the type of the given
       ## expression ``x``.
 else:
   proc `type`*(x: untyped): typeDesc {.magic: "TypeOf", noSideEffect, compileTime.} =
-    ## Builtin 'type' operator for accessing the type of an expression.
+    ## Builtin `type` operator for accessing the type of an expression.
     ## Cannot be overloaded.
     discard
 
@@ -199,45 +222,55 @@ when defined(nimHasTypeof):
     TypeOfMode* = enum ## Possible modes of `typeof`.
       typeOfProc,      ## Prefer the interpretation that means `x` is a proc call.
       typeOfIter       ## Prefer the interpretation that means `x` is an iterator call.
-  proc typeof*(x: untyped; mode = typeOfIter): typeDesc {.magic: "TypeOf", noSideEffect, compileTime.} =
-    ## Builtin 'typeof' operation for accessing the type of an expression. Since version 0.20.0.
+
+  proc typeof*(x: untyped; mode = typeOfIter): typeDesc {.
+    magic: "TypeOf", noSideEffect, compileTime.} =
+    ## Builtin `typeof` operation for accessing the type of an expression.
+    ## Since version 0.20.0.
     discard
 
 proc `not`*(x: bool): bool {.magic: "Not", noSideEffect.}
-  ## Boolean not; returns true iff ``x == false``.
+  ## Boolean not; returns true if ``x == false``.
 
 proc `and`*(x, y: bool): bool {.magic: "And", noSideEffect.}
-  ## Boolean ``and``; returns true iff ``x == y == true``.
-  ## Evaluation is lazy: if ``x`` is false,
-  ## ``y`` will not even be evaluated.
+  ## Boolean ``and``; returns true if ``x == y == true`` (if both arguments
+  ## are true).
+  ##
+  ## Evaluation is lazy: if ``x`` is false, ``y`` will not even be evaluated.
 proc `or`*(x, y: bool): bool {.magic: "Or", noSideEffect.}
-  ## Boolean ``or``; returns true iff ``not (not x and not y)``.
-  ## Evaluation is lazy: if ``x`` is true,
-  ## ``y`` will not even be evaluated.
+  ## Boolean ``or``; returns true if ``not (not x and not y)`` (if any of
+  ## the arguments is true).
+  ##
+  ## Evaluation is lazy: if ``x`` is true, ``y`` will not even be evaluated.
 proc `xor`*(x, y: bool): bool {.magic: "Xor", noSideEffect.}
-  ## Boolean `exclusive or`; returns true iff ``x != y``.
+  ## Boolean `exclusive or`; returns true if ``x != y`` (if either argument
+  ## is true while the other is false).
 
 const ThisIsSystem = true
 
 proc internalNew*[T](a: var ref T) {.magic: "New", noSideEffect.}
-  ## leaked implementation detail. Do not use.
+  ## Leaked implementation detail. Do not use.
 
 proc new*[T](a: var ref T, finalizer: proc (x: ref T) {.nimcall.}) {.
   magic: "NewFinalize", noSideEffect.}
-  ## creates a new object of type ``T`` and returns a safe (traced)
-  ## reference to it in ``a``. When the garbage collector frees the object,
-  ## `finalizer` is called. The `finalizer` may not keep a reference to the
+  ## Creates a new object of type ``T`` and returns a safe (traced)
+  ## reference to it in ``a``.
+  ##
+  ## When the garbage collector frees the object, `finalizer` is called.
+  ## The `finalizer` may not keep a reference to the
   ## object pointed to by `x`. The `finalizer` cannot prevent the GC from
-  ## freeing the object. Note: The `finalizer` refers to the type `T`, not to
-  ## the object! This means that for each object of type `T` the finalizer
-  ## will be called!
+  ## freeing the object.
+  ##
+  ## **Note**: The `finalizer` refers to the type `T`, not to the object!
+  ## This means that for each object of type `T` the finalizer will be called!
 
 proc reset*[T](obj: var T) {.magic: "Reset", noSideEffect.}
-  ## resets an object `obj` to its initial (binary zero) value. This needs to
-  ## be called before any possible `object branch transition`:idx:.
+  ## Resets an object `obj` to its initial (binary zero) value.
+  ##
+  ## This needs to be called before any possible `object branch transition`:idx:.
 
 proc wasMoved*[T](obj: var T) {.magic: "WasMoved", noSideEffect.} =
-  ## resets an object `obj` to its initial (binary zero) value to signify
+  ## Resets an object `obj` to its initial (binary zero) value to signify
   ## it was "moved" and to signify its destructor should do nothing and
   ## ideally be optimized away.
   discard
@@ -247,127 +280,179 @@ proc move*[T](x: var T): T {.magic: "Move", noSideEffect.} =
   wasMoved(x)
 
 type
-  range*{.magic: "Range".}[T] ## Generic type to construct range types.
-  array*{.magic: "Array".}[I, T]  ## Generic type to construct
-                                  ## fixed-length arrays.
-  openArray*{.magic: "OpenArray".}[T]  ## Generic type to construct open arrays.
-                                       ## Open arrays are implemented as a
-                                       ## pointer to the array data and a
-                                       ## length field.
-  varargs*{.magic: "Varargs".}[T] ## Generic type to construct a varargs type.
-  seq*{.magic: "Seq".}[T]  ## Generic type to construct sequences.
-  set*{.magic: "Set".}[T]  ## Generic type to construct bit sets.
+  range*{.magic: "Range".}[T]         ## Generic type to construct range types.
+  array*{.magic: "Array".}[I, T]      ## Generic type to construct
+                                      ## fixed-length arrays.
+  openArray*{.magic: "OpenArray".}[T] ## Generic type to construct open arrays.
+                                      ## Open arrays are implemented as a
+                                      ## pointer to the array data and a
+                                      ## length field.
+  varargs*{.magic: "Varargs".}[T]     ## Generic type to construct a varargs type.
+  seq*{.magic: "Seq".}[T]             ## Generic type to construct sequences.
+  set*{.magic: "Set".}[T]             ## Generic type to construct bit sets.
 
 when defined(nimUncheckedArrayTyp):
   type
     UncheckedArray*{.magic: "UncheckedArray".}[T]
-    ## Array with no bounds checking
+    ## Array with no bounds checking.
 else:
   type
     UncheckedArray*{.unchecked.}[T] = array[0,T]
-    ## Array with no bounds checking
+    ## Array with no bounds checking.
 
 type sink*{.magic: "BuiltinType".}[T]
 type lent*{.magic: "BuiltinType".}[T]
 
 proc high*[T: Ordinal](x: T): T {.magic: "High", noSideEffect.}
-  ## returns the highest possible value of an ordinal value `x`. As a special
-  ## semantic rule, `x` may also be a type identifier.
+  ## Returns the highest possible value of an ordinal value `x`.
   ##
-  ## .. code-block:: nim
-  ##  high(2) #=> 9223372036854775807
+  ## As a special semantic rule, `x` may also be a type identifier.
+  ##
+  ## See also:
+  ## * `low(T) <#low,T>`_
+  ##
+  ## .. code-block:: Nim
+  ##  high(2) # => 9223372036854775807
 
 proc high*[T: Ordinal|enum](x: typeDesc[T]): T {.magic: "High", noSideEffect.}
-  ## returns the highest possible value of an ordinal or enum type.
+  ## Returns the highest possible value of an ordinal or enum type.
+  ##
   ## ``high(int)`` is Nim's way of writing `INT_MAX`:idx: or `MAX_INT`:idx:.
   ##
-  ## .. code-block:: nim
-  ##  high(int) #=> 9223372036854775807
+  ## See also:
+  ## * `low(typedesc) <#low,typedesc[T]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  high(int) # => 9223372036854775807
 
 proc high*[T](x: openArray[T]): int {.magic: "High", noSideEffect.}
-  ## returns the highest possible index of a sequence `x`.
+  ## Returns the highest possible index of a sequence `x`.
   ##
-  ## .. code-block:: nim
-  ##  var s = @[1,2,3,4,5,6,7]
-  ##  high(s) #=> 6
+  ## See also:
+  ## * `low(openArray) <#low,openArray[T]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  var s = @[1, 2, 3, 4, 5, 6, 7]
+  ##  high(s) # => 6
   ##  for i in low(s)..high(s):
   ##    echo s[i]
 
 proc high*[I, T](x: array[I, T]): I {.magic: "High", noSideEffect.}
-  ## returns the highest possible index of an array `x`.
+  ## Returns the highest possible index of an array `x`.
   ##
-  ## .. code-block:: nim
-  ##  var arr = [1,2,3,4,5,6,7]
-  ##  high(arr) #=> 6
+  ## See also:
+  ## * `low(array) <#low,array[I,T]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  var arr = [1, 2, 3, 4, 5, 6, 7]
+  ##  high(arr) # => 6
   ##  for i in low(arr)..high(arr):
   ##    echo arr[i]
 
 proc high*[I, T](x: typeDesc[array[I, T]]): I {.magic: "High", noSideEffect.}
-  ## returns the highest possible index of an array type.
+  ## Returns the highest possible index of an array type.
   ##
-  ## .. code-block:: nim
-  ##  high(array[7, int]) #=> 6
+  ## See also:
+  ## * `low(typedesc[array]) <#low,typedesc[array[I,T]]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  high(array[7, int]) # => 6
 
 proc high*(x: cstring): int {.magic: "High", noSideEffect.}
-  ## returns the highest possible index of a compatible string `x`.
+  ## Returns the highest possible index of a compatible string `x`.
   ## This is sometimes an O(n) operation.
+  ##
+  ## See also:
+  ## * `low(cstring) <#low,cstring>`_
 
 proc high*(x: string): int {.magic: "High", noSideEffect.}
-  ## returns the highest possible index of a string `x`.
+  ## Returns the highest possible index of a string `x`.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `low(string) <#low,string>`_
+  ##
+  ## .. code-block:: Nim
   ##  var str = "Hello world!"
-  ##  high(str) #=> 11
+  ##  high(str) # => 11
+
+proc low*[T](x: T): T {.magic: "Low", noSideEffect.}
+  ## Returns the lowest possible value of an ordinal value `x`. As a special
+  ## semantic rule, `x` may also be a type identifier.
+  ##
+  ## See also:
+  ## * `high(T) <#high,T>`_
+  ##
+  ## .. code-block:: Nim
+  ##  low(2) # => -9223372036854775808
 
 proc low*[T: Ordinal|enum](x: typeDesc[T]): T {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible value of an ordinal or enum type.
+  ## Returns the lowest possible value of an ordinal or enum type.
+  ##
   ## ``low(int)`` is Nim's way of writing `INT_MIN`:idx: or `MIN_INT`:idx:.
   ##
-  ## .. code-block:: nim
-  ##  low(int) #=> -9223372036854775808
+  ## See also:
+  ## * `high(typedesc) <#high,typedesc[T]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  low(int) # => -9223372036854775808
 
 proc low*[T](x: openArray[T]): int {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible index of a sequence `x`.
+  ## Returns the lowest possible index of a sequence `x`.
   ##
-  ## .. code-block:: nim
-  ##  var s = @[1,2,3,4,5,6,7]
-  ##  low(s) #=> 0
+  ## See also:
+  ## * `high(openArray) <#high,openArray[T]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  var s = @[1, 2, 3, 4, 5, 6, 7]
+  ##  low(s) # => 0
+  ##  for i in low(s)..high(s):
+  ##    echo s[i]
 
 proc low*[I, T](x: array[I, T]): I {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible index of an array `x`.
+  ## Returns the lowest possible index of an array `x`.
   ##
-  ## .. code-block:: nim
-  ##  var arr = [1,2,3,4,5,6,7]
-  ##  low(arr) #=> 0
-
-proc low*[T](x: T): T {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible value of an ordinal value `x`. As a special
-  ## semantic rule, `x` may also be a type identifier.
+  ## See also:
+  ## * `high(array) <#high,array[I,T]>`_
   ##
-  ## .. code-block:: nim
-  ##  low(2) #=> -9223372036854775808
+  ## .. code-block:: Nim
+  ##  var arr = [1, 2, 3, 4, 5, 6, 7]
+  ##  low(arr) # => 0
+  ##  for i in low(arr)..high(arr):
+  ##    echo arr[i]
 
 proc low*[I, T](x: typeDesc[array[I, T]]): I {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible index of an array type.
+  ## Returns the lowest possible index of an array type.
   ##
-  ## .. code-block:: nim
-  ##  low(array[7, int]) #=> 0
+  ## See also:
+  ## * `high(typedesc[array]) <#high,typedesc[array[I,T]]>`_
+  ##
+  ## .. code-block:: Nim
+  ##  low(array[7, int]) # => 0
 
 proc low*(x: cstring): int {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible index of a compatible string `x`.
+  ## Returns the lowest possible index of a compatible string `x`.
+  ##
+  ## See also:
+  ## * `high(cstring) <#high,cstring>`_
 
 proc low*(x: string): int {.magic: "Low", noSideEffect.}
-  ## returns the lowest possible index of a string `x`.
+  ## Returns the lowest possible index of a string `x`.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `high(string) <#high,string>`_
+  ##
+  ## .. code-block:: Nim
   ##  var str = "Hello world!"
-  ##  low(str) #=> 0
+  ##  low(str) # => 0
 
 proc shallowCopy*[T](x: var T, y: T) {.noSideEffect, magic: "ShallowCopy".}
-  ## use this instead of `=` for a `shallow copy`:idx:. The shallow copy
-  ## only changes the semantics for sequences and strings (and types which
-  ## contain those). Be careful with the changed semantics though! There
-  ## is a reason why the default assignment does a deep copy of sequences
+  ## Use this instead of `=` for a `shallow copy`:idx:.
+  ##
+  ## The shallow copy only changes the semantics for sequences and strings
+  ## (and types which contain those).
+  ##
+  ## Be careful with the changed semantics though!
+  ## There is a reason why the default assignment does a deep copy of sequences
   ## and strings.
 
 when defined(nimArrIdx):
@@ -384,27 +469,36 @@ when defined(nimArrIdx):
     x: S) {.noSideEffect, magic: "ArrPut".}
 
   proc `=destroy`*[T](x: var T) {.inline, magic: "Destroy".} =
-    ## generic `destructor`:idx: implementation that can be overriden.
+    ## Generic `destructor`:idx: implementation that can be overriden.
     discard
   proc `=sink`*[T](x: var T; y: T) {.inline, magic: "Asgn".} =
-    ## generic `sink`:idx: implementation that can be overriden.
+    ## Generic `sink`:idx: implementation that can be overriden.
     shallowCopy(x, y)
 
 type
-  HSlice*[T, U] = object ## "heterogenous" slice type
-    a*: T        ## the lower bound (inclusive)
-    b*: U        ## the upper bound (inclusive)
-  Slice*[T] = HSlice[T, T] ## an alias for ``HSlice[T, T]``
+  HSlice*[T, U] = object   ## "Heterogenous" slice type.
+    a*: T                  ## The lower bound (inclusive).
+    b*: U                  ## The upper bound (inclusive).
+  Slice*[T] = HSlice[T, T] ## An alias for ``HSlice[T, T]``.
 
 proc `..`*[T, U](a: T, b: U): HSlice[T, U] {.noSideEffect, inline, magic: "DotDot".} =
-  ## binary `slice`:idx: operator that constructs an interval ``[a, b]``, both `a`
-  ## and `b` are inclusive. Slices can also be used in the set constructor
-  ## and in ordinal case statements, but then they are special-cased by the
-  ## compiler.
+  ## Binary `slice`:idx: operator that constructs an interval ``[a, b]``, both `a`
+  ## and `b` are inclusive.
+  ##
+  ## Slices can also be used in the set constructor and in ordinal case
+  ## statements, but then they are special-cased by the compiler.
+  ##
+  ## .. code-block:: Nim
+  ##   let a = [10, 20, 30, 40, 50]
+  ##   echo a[2 .. 3] # @[30, 40]
   result = HSlice[T, U](a: a, b: b)
 
 proc `..`*[T](b: T): HSlice[int, T] {.noSideEffect, inline, magic: "DotDot".} =
-  ## unary `slice`:idx: operator that constructs an interval ``[default(int), b]``
+  ## Unary `slice`:idx: operator that constructs an interval ``[default(int), b]``.
+  ##
+  ## .. code-block:: Nim
+  ##   let a = [10, 20, 30, 40, 50]
+  ##   echo a[.. 2] # @[10, 20, 30]
   result = HSlice[int, T](a: 0, b: b)
 
 when not defined(niminheritable):
@@ -420,9 +514,9 @@ else:
 
 # comparison operators:
 proc `==`*[Enum: enum](x, y: Enum): bool {.magic: "EqEnum", noSideEffect.}
-  ## Checks whether values within the *same enum* have the same underlying value
+  ## Checks whether values within the *same enum* have the same underlying value.
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##  type
   ##    Enum1 = enum
   ##      Field1 = 3, Field2
@@ -434,51 +528,121 @@ proc `==`*[Enum: enum](x, y: Enum): bool {.magic: "EqEnum", noSideEffect.}
   ##  echo (e1 == e2) # true
   ##  echo (e1 == Place2) # raises error
 proc `==`*(x, y: pointer): bool {.magic: "EqRef", noSideEffect.}
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##  var # this is a wildly dangerous example
   ##    a = cast[pointer](0)
   ##    b = cast[pointer](nil)
   ##  echo (a == b) # true due to the special meaning of `nil`/0 as a pointer
 proc `==`*(x, y: string): bool {.magic: "EqStr", noSideEffect.}
-  ## Checks for equality between two `string` variables
+  ## Checks for equality between two `string` variables.
 
 proc `==`*(x, y: char): bool {.magic: "EqCh", noSideEffect.}
-  ## Checks for equality between two `char` variables
+  ## Checks for equality between two `char` variables.
 proc `==`*(x, y: bool): bool {.magic: "EqB", noSideEffect.}
-  ## Checks for equality between two `bool` variables
+  ## Checks for equality between two `bool` variables.
 proc `==`*[T](x, y: set[T]): bool {.magic: "EqSet", noSideEffect.}
-  ## Checks for equality between two variables of type `set`
+  ## Checks for equality between two variables of type `set`.
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##  var a = {1, 2, 2, 3} # duplication in sets is ignored
   ##  var b = {1, 2, 3}
   ##  echo (a == b) # true
 proc `==`*[T](x, y: ref T): bool {.magic: "EqRef", noSideEffect.}
-  ## Checks that two `ref` variables refer to the same item
+  ## Checks that two `ref` variables refer to the same item.
 proc `==`*[T](x, y: ptr T): bool {.magic: "EqRef", noSideEffect.}
-  ## Checks that two `ptr` variables refer to the same item
+  ## Checks that two `ptr` variables refer to the same item.
 proc `==`*[T: proc](x, y: T): bool {.magic: "EqProc", noSideEffect.}
-  ## Checks that two `proc` variables refer to the same procedure
+  ## Checks that two `proc` variables refer to the same procedure.
 
 proc `<=`*[Enum: enum](x, y: Enum): bool {.magic: "LeEnum", noSideEffect.}
 proc `<=`*(x, y: string): bool {.magic: "LeStr", noSideEffect.}
+  ## Compares two strings and returns true if `x` is lexicographically
+  ## before `y` (uppercase letters come before lowercase letters).
+  ##
+  ## .. code-block:: Nim
+  ##     let
+  ##       a = "abc"
+  ##       b = "abd"
+  ##       c = "ZZZ"
+  ##     assert a <= b
+  ##     assert a <= a
+  ##     assert (a <= c) == false
 proc `<=`*(x, y: char): bool {.magic: "LeCh", noSideEffect.}
+  ## Compares two chars and returns true if `x` is lexicographically
+  ## before `y` (uppercase letters come before lowercase letters).
+  ##
+  ## .. code-block:: Nim
+  ##     let
+  ##       a = 'a'
+  ##       b = 'b'
+  ##       c = 'Z'
+  ##     assert a <= b
+  ##     assert a <= a
+  ##     assert (a <= c) == false
 proc `<=`*[T](x, y: set[T]): bool {.magic: "LeSet", noSideEffect.}
+  ## Returns true if `x` is a subset of `y`.
+  ##
+  ## A subset `x` has all of its members in `y` and `y` doesn't necessarily
+  ## have more members than `x`. That is, `x` can be equal to `y`.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = {3, 5}
+  ##     b = {1, 3, 5, 7}
+  ##     c = {2}
+  ##   assert a <= b
+  ##   assert a <= a
+  ##   assert (a <= c) == false
 proc `<=`*(x, y: bool): bool {.magic: "LeB", noSideEffect.}
 proc `<=`*[T](x, y: ref T): bool {.magic: "LePtr", noSideEffect.}
 proc `<=`*(x, y: pointer): bool {.magic: "LePtr", noSideEffect.}
 
 proc `<`*[Enum: enum](x, y: Enum): bool {.magic: "LtEnum", noSideEffect.}
 proc `<`*(x, y: string): bool {.magic: "LtStr", noSideEffect.}
+  ## Compares two strings and returns true if `x` is lexicographically
+  ## before `y` (uppercase letters come before lowercase letters).
+  ##
+  ## .. code-block:: Nim
+  ##     let
+  ##       a = "abc"
+  ##       b = "abd"
+  ##       c = "ZZZ"
+  ##     assert a < b
+  ##     assert (a < a) == false
+  ##     assert (a < c) == false
 proc `<`*(x, y: char): bool {.magic: "LtCh", noSideEffect.}
+  ## Compares two chars and returns true if `x` is lexicographically
+  ## before `y` (uppercase letters come before lowercase letters).
+  ##
+  ## .. code-block:: Nim
+  ##     let
+  ##       a = 'a'
+  ##       b = 'b'
+  ##       c = 'Z'
+  ##     assert a < b
+  ##     assert (a < a) == false
+  ##     assert (a < c) == false
 proc `<`*[T](x, y: set[T]): bool {.magic: "LtSet", noSideEffect.}
+  ## Returns true if `x` is a strict or proper subset of `y`.
+  ##
+  ## A strict or proper subset `x` has all of its members in `y` but `y` has
+  ## more elements than `y`.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = {3, 5}
+  ##     b = {1, 3, 5, 7}
+  ##     c = {2}
+  ##   assert a < b
+  ##   assert (a < a) == false
+  ##   assert (a < c) == false
 proc `<`*(x, y: bool): bool {.magic: "LtB", noSideEffect.}
 proc `<`*[T](x, y: ref T): bool {.magic: "LtPtr", noSideEffect.}
 proc `<`*[T](x, y: ptr T): bool {.magic: "LtPtr", noSideEffect.}
 proc `<`*(x, y: pointer): bool {.magic: "LtPtr", noSideEffect.}
 
 template `!=`*(x, y: untyped): untyped =
-  ## unequals operator. This is a shorthand for ``not (x == y)``.
+  ## Unequals operator. This is a shorthand for ``not (x == y)``.
   not (x == y)
 
 template `>=`*(x, y: untyped): untyped =
@@ -491,13 +655,13 @@ template `>`*(x, y: untyped): untyped =
 
 const
   appType* {.magic: "AppType"}: string = ""
-    ## a string that describes the application type. Possible values:
-    ## "console", "gui", "lib".
+    ## A string that describes the application type. Possible values:
+    ## `"console"`, `"gui"`, `"lib"`.
 
 include "system/inclrtl"
 
-const NoFakeVars* = defined(nimscript) ## true if the backend doesn't support \
-  ## "fake variables" like 'var EBADF {.importc.}: cint'.
+const NoFakeVars* = defined(nimscript) ## `true` if the backend doesn't support \
+  ## "fake variables" like `var EBADF {.importc.}: cint`.
 
 when not defined(JS) and not defined(gcDestructors):
   type
@@ -518,27 +682,29 @@ when not defined(JS) and not defined(nimscript):
   include "system/hti"
 
 type
-  byte* = uint8 ## this is an alias for ``uint8``, that is an unsigned
-                ## int 8 bits wide.
+  byte* = uint8 ## This is an alias for ``uint8``, that is an unsigned
+                ## integer, 8 bits wide.
 
   Natural* = range[0..high(int)]
-    ## is an int type ranging from zero to the maximum value
-    ## of an int. This type is often useful for documentation and debugging.
+    ## is an `int` type ranging from zero to the maximum value
+    ## of an `int`. This type is often useful for documentation and debugging.
 
   Positive* = range[1..high(int)]
-    ## is an int type ranging from one to the maximum value
-    ## of an int. This type is often useful for documentation and debugging.
+    ## is an `int` type ranging from one to the maximum value
+    ## of an `int`. This type is often useful for documentation and debugging.
 
   RootObj* {.compilerProc, inheritable.} =
-    object ## the root of Nim's object hierarchy. Objects should
-           ## inherit from RootObj or one of its descendants. However,
-           ## objects that have no ancestor are allowed.
-  RootRef* = ref RootObj ## reference to RootObj
+    object ## The root of Nim's object hierarchy.
+           ##
+           ## Objects should inherit from `RootObj` or one of its descendants.
+           ## However, objects that have no ancestor are also allowed.
+  RootRef* = ref RootObj ## Reference to `RootObj`.
 
   RootEffect* {.compilerproc.} = object of RootObj ## \
-    ## base effect class; each effect should
-    ## inherit from `RootEffect` unless you know what
-    ## you doing.
+    ## Base effect class.
+    ##
+    ## Each effect should inherit from `RootEffect` unless you know what
+    ## you're doing.
   TimeEffect* = object of RootEffect   ## Time effect.
   IOEffect* = object of RootEffect     ## IO effect.
   ReadIOEffect* = object of IOEffect   ## Effect describing a read IO operation.
@@ -546,22 +712,22 @@ type
   ExecIOEffect* = object of IOEffect   ## Effect describing an executing IO operation.
 
   StackTraceEntry* = object ## In debug mode exceptions store the stack trace that led
-                            ## to them. A StackTraceEntry is a single entry of the
+                            ## to them. A `StackTraceEntry` is a single entry of the
                             ## stack trace.
-    procname*: cstring  ## name of the proc that is currently executing
-    line*: int          ## line number of the proc that is currently executing
-    filename*: cstring  ## filename of the proc that is currently executing
+    procname*: cstring      ## Name of the proc that is currently executing.
+    line*: int              ## Line number of the proc that is currently executing.
+    filename*: cstring      ## Filename of the proc that is currently executing.
 
   Exception* {.compilerproc, magic: "Exception".} = object of RootObj ## \
     ## Base exception class.
     ##
     ## Each exception has to inherit from `Exception`. See the full `exception
     ## hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-    parent*: ref Exception ## parent exception (can be used as a stack)
-    name*: cstring ## The exception's name is its Nim identifier.
-                   ## This field is filled automatically in the
-                   ## ``raise`` statement.
-    msg* {.exportc: "message".}: string ## the exception's message. Not
+    parent*: ref Exception ## Parent exception (can be used as a stack).
+    name*: cstring         ## The exception's name is its Nim identifier.
+                           ## This field is filled automatically in the
+                           ## ``raise`` statement.
+    msg* {.exportc: "message".}: string ## The exception's message. Not
                                         ## providing an exception message
                                         ## is bad style.
     when defined(js):
@@ -662,13 +828,13 @@ type
     ## The operation produced a result that cannot be represented with infinite
     ## precision -- for example: ``2.0 / 3.0, log(1.1)``
     ##
-    ## **NOTE**: Nim currently does not detect these!
+    ## **Note**: Nim currently does not detect these!
   DeadThreadError* = object of Defect ## \
     ## Raised if it is attempted to send a message to a dead thread.
   NilAccessError* = object of Defect ## \
     ## Raised on dereferences of ``nil`` pointers.
     ##
-    ## This is only raised if the ``segfaults.nim`` module was imported!
+    ## This is only raised if the `segfaults module <segfaults.html>`_ was imported!
 
 when defined(js) or defined(nimdoc):
   type
@@ -676,25 +842,34 @@ when defined(js) or defined(nimdoc):
       ## Root type of the JavaScript object hierarchy
 
 proc unsafeNew*[T](a: var ref T, size: Natural) {.magic: "New", noSideEffect.}
-  ## creates a new object of type ``T`` and returns a safe (traced)
-  ## reference to it in ``a``. This is **unsafe** as it allocates an object
-  ## of the passed ``size``. This should only be used for optimization
-  ## purposes when you know what you're doing!
+  ## Creates a new object of type ``T`` and returns a safe (traced)
+  ## reference to it in ``a``.
+  ##
+  ## This is **unsafe** as it allocates an object of the passed ``size``.
+  ## This should only be used for optimization purposes when you know
+  ## what you're doing!
+  ##
+  ## See also:
+  ## * `new <#new,ref.T,proc(ref.T)>`_
 
 proc sizeof*[T](x: T): int {.magic: "SizeOf", noSideEffect.}
-  ## returns the size of ``x`` in bytes. Since this is a low-level proc,
-  ## its usage is discouraged - using ``new`` for the most cases suffices
-  ## that one never needs to know ``x``'s size. As a special semantic rule,
-  ## ``x`` may also be a type identifier (``sizeof(int)`` is valid).
+  ## Returns the size of ``x`` in bytes.
+  ##
+  ## Since this is a low-level proc,
+  ## its usage is discouraged - using `new <#new,ref.T,proc(ref.T)>`_ for
+  ## the most cases suffices that one never needs to know ``x``'s size.
+  ##
+  ## As a special semantic rule, ``x`` may also be a type identifier
+  ## (``sizeof(int)`` is valid).
   ##
   ## Limitations: If used for types that are imported from C or C++,
   ## sizeof should fallback to the ``sizeof`` in the C compiler. The
   ## result isn't available for the Nim compiler and therefore can't
   ## be used inside of macros.
   ##
-  ## .. code-block:: nim
-  ##  sizeof('A') #=> 1
-  ##  sizeof(2) #=> 8
+  ## .. code-block:: Nim
+  ##  sizeof('A') # => 1
+  ##  sizeof(2) # => 8
 
 when defined(nimHasalignOf):
   proc alignof*[T](x: T): int {.magic: "AlignOf", noSideEffect.}
@@ -715,75 +890,95 @@ when defined(nimtypedescfixed):
   proc sizeof*(x: typedesc): int {.magic: "SizeOf", noSideEffect.}
 
 proc `<`*[T](x: Ordinal[T]): T {.magic: "UnaryLt", noSideEffect, deprecated.}
-  ## unary ``<`` that can be used for nice looking excluding ranges:
-  ##
-  ## .. code-block:: nim
-  ##   for i in 0 .. <10: echo i #=> 0 1 2 3 4 5 6 7 8 9
-  ##
-  ## Semantically this is the same as ``pred``.
-  ##
   ## **Deprecated since version 0.18.0**. For the common excluding range
   ## write ``0 ..< 10`` instead of ``0 .. < 10`` (look at the spacing).
   ## For ``<x`` write ``pred(x)``.
+  ##
+  ## Unary ``<`` that can be used for excluding ranges.
+  ## Semantically this is the same as `pred <#pred,T,int>`_.
+  ##
+  ## .. code-block:: Nim
+  ##   for i in 0 .. <10: echo i # => 0 1 2 3 4 5 6 7 8 9
+  ##
 
 proc succ*[T: Ordinal](x: T, y = 1): T {.magic: "Succ", noSideEffect.}
-  ## returns the ``y``-th successor of the value ``x``. ``T`` has to be
-  ## an ordinal type. If such a value does not exist, ``EOutOfRange`` is raised
+  ## Returns the ``y``-th successor (default: 1) of the value ``x``.
+  ## ``T`` has to be an ordinal type.
+  ##
+  ## If such a value does not exist, ``OverflowError`` is raised
   ## or a compile time error occurs.
+  ##
+  ## .. code-block:: Nim
+  ##   let x = 5
+  ##   echo succ(5)    # => 6
+  ##   echo succ(5, 3) # => 8
 
 proc pred*[T: Ordinal](x: T, y = 1): T {.magic: "Pred", noSideEffect.}
-  ## returns the ``y``-th predecessor of the value ``x``. ``T`` has to be
-  ## an ordinal type. If such a value does not exist, ``EOutOfRange`` is raised
+  ## Returns the ``y``-th predecessor (default: 1) of the value ``x``.
+  ## ``T`` has to be an ordinal type.
+  ##
+  ## If such a value does not exist, ``OverflowError`` is raised
   ## or a compile time error occurs.
+  ##
+  ## .. code-block:: Nim
+  ##   let x = 5
+  ##   echo pred(5)    # => 4
+  ##   echo pred(5, 3) # => 2
 
 proc inc*[T: Ordinal|uint|uint64](x: var T, y = 1) {.magic: "Inc", noSideEffect.}
-  ## increments the ordinal ``x`` by ``y``. If such a value does not
-  ## exist, ``EOutOfRange`` is raised or a compile time error occurs. This is a
-  ## short notation for: ``x = succ(x, y)``.
+  ## Increments the ordinal ``x`` by ``y``.
   ##
-  ## .. code-block:: nim
+  ## If such a value does not exist, ``OverflowError`` is raised or a compile
+  ## time error occurs. This is a short notation for: ``x = succ(x, y)``.
+  ##
+  ## .. code-block:: Nim
   ##  var i = 2
-  ##  inc(i) #=> 3
-  ##  inc(i, 3) #=> 6
+  ##  inc(i)    # i <- 3
+  ##  inc(i, 3) # i <- 6
 
 proc dec*[T: Ordinal|uint|uint64](x: var T, y = 1) {.magic: "Dec", noSideEffect.}
-  ## decrements the ordinal ``x`` by ``y``. If such a value does not
-  ## exist, ``EOutOfRange`` is raised or a compile time error occurs. This is a
-  ## short notation for: ``x = pred(x, y)``.
+  ## Decrements the ordinal ``x`` by ``y``.
   ##
-  ## .. code-block:: nim
+  ## If such a value does not exist, ``OverflowError`` is raised or a compile
+  ## time error occurs. This is a short notation for: ``x = pred(x, y)``.
+  ##
+  ## .. code-block:: Nim
   ##  var i = 2
-  ##  dec(i) #=> 1
-  ##  dec(i, 3) #=> -2
+  ##  dec(i)    # i <- 1
+  ##  dec(i, 3) # i <- -2
 
 proc newSeq*[T](s: var seq[T], len: Natural) {.magic: "NewSeq", noSideEffect.}
-  ## creates a new sequence of type ``seq[T]`` with length ``len``.
+  ## Creates a new sequence of type ``seq[T]`` with length ``len``.
   ## This is equivalent to ``s = @[]; setlen(s, len)``, but more
   ## efficient since no reallocation is needed.
   ##
-  ## Note that the sequence will be filled with zeroed entries, which can be a
-  ## problem for sequences containing strings since their value will be
-  ## ``nil``. After the creation of the sequence you should assign entries to
+  ## Note that the sequence will be filled with zeroed entries.
+  ## After the creation of the sequence you should assign entries to
   ## the sequence instead of adding them. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   var inputStrings : seq[string]
   ##   newSeq(inputStrings, 3)
+  ##   assert len(inputStrings) == 3
   ##   inputStrings[0] = "The fourth"
   ##   inputStrings[1] = "assignment"
   ##   inputStrings[2] = "would crash"
   ##   #inputStrings[3] = "out of bounds"
 
 proc newSeq*[T](len = 0.Natural): seq[T] =
-  ## creates a new sequence of type ``seq[T]`` with length ``len``.
+  ## Creates a new sequence of type ``seq[T]`` with length ``len``.
   ##
-  ## Note that the sequence will be filled with zeroed entries, which can be a
-  ## problem for sequences containing strings since their value will be
-  ## ``nil``. After the creation of the sequence you should assign entries to
-  ## the sequence instead of adding them. Example:
+  ## Note that the sequence will be filled with zeroed entries.
+  ## After the creation of the sequence you should assign entries to
+  ## the sequence instead of adding them.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `newSeqOfCap <#newSeqOfCap,Natural>`_
+  ## * `newSeqUninitialized <#newSeqUninitialized,Natural>`_
+  ##
+  ## .. code-block:: Nim
   ##   var inputStrings = newSeq[string](3)
+  ##   assert len(inputStrings) == 3
   ##   inputStrings[0] = "The fourth"
   ##   inputStrings[1] = "assignment"
   ##   inputStrings[2] = "would crash"
@@ -792,107 +987,129 @@ proc newSeq*[T](len = 0.Natural): seq[T] =
 
 proc newSeqOfCap*[T](cap: Natural): seq[T] {.
   magic: "NewSeqOfCap", noSideEffect.} =
-  ## creates a new sequence of type ``seq[T]`` with length 0 and capacity
+  ## Creates a new sequence of type ``seq[T]`` with length zero and capacity
   ## ``cap``.
+  ##
+  ## .. code-block:: Nim
+  ##   var x = newSeqOfCap[int](5)
+  ##   assert len(x) == 0
+  ##   x.add(10)
+  ##   assert len(x) == 1
   discard
 
 when not defined(JS) and not defined(gcDestructors):
   # XXX enable this for --gc:destructors
   proc newSeqUninitialized*[T: SomeNumber](len: Natural): seq[T] =
-    ## creates a new sequence of type ``seq[T]`` with length ``len``.
+    ## Creates a new sequence of type ``seq[T]`` with length ``len``.
     ##
     ## Only available for numbers types. Note that the sequence will be
     ## uninitialized. After the creation of the sequence you should assign
     ## entries to the sequence instead of adding them.
-
+    ##
+    ## .. code-block:: Nim
+    ##   var x = newSeqUninitialized[int](3)
+    ##   assert len(x) == 3
+    ##   x[0] = 10
     result = newSeqOfCap[T](len)
     var s = cast[PGenericSeq](result)
     s.len = len
 
 proc len*[TOpenArray: openArray|varargs](x: TOpenArray): int {.
   magic: "LengthOpenArray", noSideEffect.}
-  ## returns the length of an openarray.
+  ## Returns the length of an openarray.
   ##
-  ## .. code-block:: nim
-  ##  var s = [1,1,1,1,1]
-  ##  len(s) #=> 5
+  ## .. code-block:: Nim
+  ##   var s = [1, 1, 1, 1, 1]
+  ##   echo len(s) # => 5
 
 proc len*(x: string): int {.magic: "LengthStr", noSideEffect.}
-  ## returns the length of a string.
+  ## Returns the length of a string.
   ##
-  ## .. code-block:: nim
-  ##  var str = "Hello world!"
-  ##  len(str) #=> 12
+  ## .. code-block:: Nim
+  ##   var str = "Hello world!"
+  ##   echo len(str) # => 12
 
 proc len*(x: cstring): int {.magic: "LengthStr", noSideEffect.}
-  ## returns the length of a compatible string. This is sometimes
+  ## Returns the length of a compatible string. This is sometimes
   ## an O(n) operation.
   ##
-  ## .. code-block:: nim
-  ##  var str: cstring = "Hello world!"
-  ##  len(str) #=> 12
+  ## .. code-block:: Nim
+  ##   var str: cstring = "Hello world!"
+  ##   len(str) # => 12
 
 proc len*(x: (type array)|array): int {.magic: "LengthArray", noSideEffect.}
-  ## returns the length of an array or an array type.
+  ## Returns the length of an array or an array type.
   ## This is roughly the same as ``high(T)-low(T)+1``.
   ##
-  ## .. code-block:: nim
-  ##  var arr = [1,1,1,1,1]
-  ##  len(arr) #=> 5
-  ##  len(array[3..8, int]) #=> 6
+  ## .. code-block:: Nim
+  ##   var arr = [1, 1, 1, 1, 1]
+  ##   echo len(arr) # => 5
+  ##   echo len(array[3..8, int]) # => 6
 
 proc len*[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}
-  ## returns the length of a sequence.
+  ## Returns the length of a sequence.
   ##
-  ## .. code-block:: nim
-  ##  var s = @[1,1,1,1,1]
-  ##  len(s) #=> 5
+  ## .. code-block:: Nim
+  ##   var s = @[1, 1, 1, 1, 1]
+  ##   echo len(s) # => 5
 
 # set routines:
 proc incl*[T](x: var set[T], y: T) {.magic: "Incl", noSideEffect.}
-  ## includes element ``y`` to the set ``x``. This is the same as
+  ## Includes element ``y`` in the set ``x``. This is the same as
   ## ``x = x + {y}``, but it might be more efficient.
   ##
-  ## .. code-block:: nim
-  ##  var a = initSet[int](4)
-  ##  a.incl(2) #=> {2}
-  ##  a.incl(3) #=> {2, 3}
+  ## .. code-block:: Nim
+  ##   var a = {1, 3, 5}
+  ##   a.incl(2) # a <- {1, 2, 3, 5}
+  ##   a.incl(4) # a <- {1, 2, 3, 4, 5}
 
-template incl*[T](s: var set[T], flags: set[T]) =
-  ## includes the set of flags to the set ``x``.
-  s = s + flags
+template incl*[T](x: var set[T], y: set[T]) =
+  ## Includes the set ``y`` in the set ``x``.
+  ##
+  ## .. code-block:: Nim
+  ##   var a = {1, 3, 5, 7}
+  ##   var b = {4, 5, 6}
+  ##   a.incl(b)  # a <- {1, 3, 4, 5, 6, 7}
+  x = x + y
 
 proc excl*[T](x: var set[T], y: T) {.magic: "Excl", noSideEffect.}
-  ## excludes element ``y`` to the set ``x``. This is the same as
+  ## Excludes element ``y`` from the set ``x``. This is the same as
   ## ``x = x - {y}``, but it might be more efficient.
   ##
-  ## .. code-block:: nim
-  ##  var b = {2,3,5,6,12,545}
-  ##  b.excl(5)  #=> {2,3,6,12,545}
+  ## .. code-block:: Nim
+  ##   var b = {2, 3, 5, 6, 12, 545}
+  ##   b.excl(5)  # b <- {2, 3, 6, 12, 545}
 
-template excl*[T](s: var set[T], flags: set[T]) =
-  ## excludes the set of flags to ``x``.
-  s = s - flags
+template excl*[T](x: var set[T], y: set[T]) =
+  ## Excludes the set ``y`` from the set ``x``.
+  ##
+  ## .. code-block:: Nim
+  ##   var a = {1, 3, 5, 7}
+  ##   var b = {3, 4, 5}
+  ##   a.excl(b)  # a <- {1, 7}
+  x = x - y
 
 proc card*[T](x: set[T]): int {.magic: "Card", noSideEffect.}
-  ## returns the cardinality of the set ``x``, i.e. the number of elements
+  ## Returns the cardinality of the set ``x``, i.e. the number of elements
   ## in the set.
   ##
-  ## .. code-block:: nim
-  ##  var i = {1,2,3,4}
-  ##  card(i) #=> 4
+  ## .. code-block:: Nim
+  ##   var a = {1, 3, 5, 7}
+  ##   echo card(a) # => 4
 
 proc ord*[T: Ordinal|enum](x: T): int {.magic: "Ord", noSideEffect.}
-  ## returns the internal int value of an ordinal value ``x``.
+  ## Returns the internal int value of an ordinal value ``x``.
   ##
-  ## .. code-block:: nim
-  ##  ord('A') #=> 65
+  ## .. code-block:: Nim
+  ##   echo ord('A') # => 65
+  ##   echo ord('a') # => 97
 
 proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.}
-  ## converts an int in the range 0..255 to a character.
+  ## Converts an int in the range 0..255 to a character.
   ##
-  ## .. code-block:: nim
-  ##  chr(65) #=> A
+  ## .. code-block:: Nim
+  ##   echo chr(65) # => A
+  ##   echo chr(97) # => a
 
 # --------------------------------------------------------------------------
 # built-in operators
@@ -946,68 +1163,73 @@ when not defined(JS):
 
 # integer calculations:
 proc `+`*(x: int): int {.magic: "UnaryPlusI", noSideEffect.}
+  ## Unary `+` operator for an integer. Has no effect.
 proc `+`*(x: int8): int8 {.magic: "UnaryPlusI", noSideEffect.}
 proc `+`*(x: int16): int16 {.magic: "UnaryPlusI", noSideEffect.}
 proc `+`*(x: int32): int32 {.magic: "UnaryPlusI", noSideEffect.}
 proc `+`*(x: int64): int64 {.magic: "UnaryPlusI", noSideEffect.}
-  ## Unary `+` operator for an integer. Has no effect.
 
 proc `-`*(x: int): int {.magic: "UnaryMinusI", noSideEffect.}
+  ## Unary `-` operator for an integer. Negates `x`.
 proc `-`*(x: int8): int8 {.magic: "UnaryMinusI", noSideEffect.}
 proc `-`*(x: int16): int16 {.magic: "UnaryMinusI", noSideEffect.}
 proc `-`*(x: int32): int32 {.magic: "UnaryMinusI", noSideEffect.}
 proc `-`*(x: int64): int64 {.magic: "UnaryMinusI64", noSideEffect.}
-  ## Unary `-` operator for an integer. Negates `x`.
 
 proc `not`*(x: int): int {.magic: "BitnotI", noSideEffect.}
+  ## Computes the `bitwise complement` of the integer `x`.
+  ##
+  ## .. code-block:: Nim
+  ##   var
+  ##     a = 0'u8
+  ##     b = 0'i8
+  ##     c = 1000'u16
+  ##     d = 1000'i16
+  ##
+  ##   echo not a # => 255
+  ##   echo not b # => -1
+  ##   echo not c # => 64535
+  ##   echo not d # => -1001
 proc `not`*(x: int8): int8 {.magic: "BitnotI", noSideEffect.}
 proc `not`*(x: int16): int16 {.magic: "BitnotI", noSideEffect.}
 proc `not`*(x: int32): int32 {.magic: "BitnotI", noSideEffect.}
-  ## computes the `bitwise complement` of the integer `x`.
-
 when defined(nimnomagic64):
   proc `not`*(x: int64): int64 {.magic: "BitnotI", noSideEffect.}
 else:
   proc `not`*(x: int64): int64 {.magic: "BitnotI64", noSideEffect.}
 
 proc `+`*(x, y: int): int {.magic: "AddI", noSideEffect.}
+  ## Binary `+` operator for an integer.
 proc `+`*(x, y: int8): int8 {.magic: "AddI", noSideEffect.}
 proc `+`*(x, y: int16): int16 {.magic: "AddI", noSideEffect.}
 proc `+`*(x, y: int32): int32 {.magic: "AddI", noSideEffect.}
-  ## Binary `+` operator for an integer.
-
 when defined(nimnomagic64):
   proc `+`*(x, y: int64): int64 {.magic: "AddI", noSideEffect.}
 else:
   proc `+`*(x, y: int64): int64 {.magic: "AddI64", noSideEffect.}
 
 proc `-`*(x, y: int): int {.magic: "SubI", noSideEffect.}
+  ## Binary `-` operator for an integer.
 proc `-`*(x, y: int8): int8 {.magic: "SubI", noSideEffect.}
 proc `-`*(x, y: int16): int16 {.magic: "SubI", noSideEffect.}
 proc `-`*(x, y: int32): int32 {.magic: "SubI", noSideEffect.}
-  ## Binary `-` operator for an integer.
-
 when defined(nimnomagic64):
   proc `-`*(x, y: int64): int64 {.magic: "SubI", noSideEffect.}
 else:
   proc `-`*(x, y: int64): int64 {.magic: "SubI64", noSideEffect.}
 
 proc `*`*(x, y: int): int {.magic: "MulI", noSideEffect.}
+  ## Binary `*` operator for an integer.
 proc `*`*(x, y: int8): int8 {.magic: "MulI", noSideEffect.}
 proc `*`*(x, y: int16): int16 {.magic: "MulI", noSideEffect.}
 proc `*`*(x, y: int32): int32 {.magic: "MulI", noSideEffect.}
-  ## Binary `*` operator for an integer.
-
 when defined(nimnomagic64):
   proc `*`*(x, y: int64): int64 {.magic: "MulI", noSideEffect.}
 else:
   proc `*`*(x, y: int64): int64 {.magic: "MulI64", noSideEffect.}
 
 proc `div`*(x, y: int): int {.magic: "DivI", noSideEffect.}
-proc `div`*(x, y: int8): int8 {.magic: "DivI", noSideEffect.}
-proc `div`*(x, y: int16): int16 {.magic: "DivI", noSideEffect.}
-proc `div`*(x, y: int32): int32 {.magic: "DivI", noSideEffect.}
-  ## computes the integer division. This is roughly the same as
+  ## Computes the integer division. This is roughly the same as
   ## ``trunc(x/y)``.
   ##
   ## .. code-block:: Nim
@@ -1018,17 +1240,16 @@ proc `div`*(x, y: int32): int32 {.magic: "DivI", noSideEffect.}
   ##   (-7 div  3) == -2
   ##   ( 7 div -3) == -2
   ##   (-7 div -3) ==  2
-
+proc `div`*(x, y: int8): int8 {.magic: "DivI", noSideEffect.}
+proc `div`*(x, y: int16): int16 {.magic: "DivI", noSideEffect.}
+proc `div`*(x, y: int32): int32 {.magic: "DivI", noSideEffect.}
 when defined(nimnomagic64):
   proc `div`*(x, y: int64): int64 {.magic: "DivI", noSideEffect.}
 else:
   proc `div`*(x, y: int64): int64 {.magic: "DivI64", noSideEffect.}
 
 proc `mod`*(x, y: int): int {.magic: "ModI", noSideEffect.}
-proc `mod`*(x, y: int8): int8 {.magic: "ModI", noSideEffect.}
-proc `mod`*(x, y: int16): int16 {.magic: "ModI", noSideEffect.}
-proc `mod`*(x, y: int32): int32 {.magic: "ModI", noSideEffect.}
-  ## computes the integer modulo operation (remainder).
+  ## Computes the integer modulo operation (remainder).
   ## This is the same as
   ## ``x - (x div y) * y``.
   ##
@@ -1037,7 +1258,9 @@ proc `mod`*(x, y: int32): int32 {.magic: "ModI", noSideEffect.}
   ##   (-7 mod  5) == -2
   ##   ( 7 mod -5) ==  2
   ##   (-7 mod -5) == -2
-
+proc `mod`*(x, y: int8): int8 {.magic: "ModI", noSideEffect.}
+proc `mod`*(x, y: int16): int16 {.magic: "ModI", noSideEffect.}
+proc `mod`*(x, y: int32): int32 {.magic: "ModI", noSideEffect.}
 when defined(nimnomagic64):
   proc `mod`*(x, y: int64): int64 {.magic: "ModI", noSideEffect.}
 else:
@@ -1045,29 +1268,31 @@ else:
 
 when defined(nimNewShiftOps):
   proc `shr`*(x: int, y: SomeInteger): int {.magic: "ShrI", noSideEffect.}
-  proc `shr`*(x: int8, y: SomeInteger): int8 {.magic: "ShrI", noSideEffect.}
-  proc `shr`*(x: int16, y: SomeInteger): int16 {.magic: "ShrI", noSideEffect.}
-  proc `shr`*(x: int32, y: SomeInteger): int32 {.magic: "ShrI", noSideEffect.}
-  proc `shr`*(x: int64, y: SomeInteger): int64 {.magic: "ShrI", noSideEffect.}
-    ## computes the `shift right` operation of `x` and `y`, filling
+    ## Computes the `shift right` operation of `x` and `y`, filling
     ## vacant bit positions with zeros.
     ##
+    ## See also:
+    ## * `ashr proc <#ashr,int,SomeInteger>`_
+    ##
     ## .. code-block:: Nim
     ##   0b0001_0000'i8 shr 2 == 0b0000_0100'i8
     ##   0b1000_0000'i8 shr 8 == 0b0000_0000'i8
     ##   0b0000_0001'i8 shr 1 == 0b0000_0000'i8
-
+  proc `shr`*(x: int8, y: SomeInteger): int8 {.magic: "ShrI", noSideEffect.}
+  proc `shr`*(x: int16, y: SomeInteger): int16 {.magic: "ShrI", noSideEffect.}
+  proc `shr`*(x: int32, y: SomeInteger): int32 {.magic: "ShrI", noSideEffect.}
+  proc `shr`*(x: int64, y: SomeInteger): int64 {.magic: "ShrI", noSideEffect.}
 
   proc `shl`*(x: int, y: SomeInteger): int {.magic: "ShlI", noSideEffect.}
-  proc `shl`*(x: int8, y: SomeInteger): int8 {.magic: "ShlI", noSideEffect.}
-  proc `shl`*(x: int16, y: SomeInteger): int16 {.magic: "ShlI", noSideEffect.}
-  proc `shl`*(x: int32, y: SomeInteger): int32 {.magic: "ShlI", noSideEffect.}
-  proc `shl`*(x: int64, y: SomeInteger): int64 {.magic: "ShlI", noSideEffect.}
-    ## computes the `shift left` operation of `x` and `y`.
+    ## Computes the `shift left` operation of `x` and `y`.
     ##
     ## .. code-block:: Nim
     ##  1'i32 shl 4 == 0x0000_0010
     ##  1'i64 shl 4 == 0x0000_0000_0000_0010
+  proc `shl`*(x: int8, y: SomeInteger): int8 {.magic: "ShlI", noSideEffect.}
+  proc `shl`*(x: int16, y: SomeInteger): int16 {.magic: "ShlI", noSideEffect.}
+  proc `shl`*(x: int32, y: SomeInteger): int32 {.magic: "ShlI", noSideEffect.}
+  proc `shl`*(x: int64, y: SomeInteger): int64 {.magic: "ShlI", noSideEffect.}
 else:
   proc `shr`*(x, y: int): int {.magic: "ShrI", noSideEffect.}
   proc `shr`*(x, y: int8): int8 {.magic: "ShrI", noSideEffect.}
@@ -1083,141 +1308,158 @@ else:
 
 when defined(nimAshr):
   proc ashr*(x: int, y: SomeInteger): int {.magic: "AshrI", noSideEffect.}
-  proc ashr*(x: int8, y: SomeInteger): int8 {.magic: "AshrI", noSideEffect.}
-  proc ashr*(x: int16, y: SomeInteger): int16 {.magic: "AshrI", noSideEffect.}
-  proc ashr*(x: int32, y: SomeInteger): int32 {.magic: "AshrI", noSideEffect.}
-  proc ashr*(x: int64, y: SomeInteger): int64 {.magic: "AshrI", noSideEffect.}
     ## Shifts right by pushing copies of the leftmost bit in from the left,
     ## and let the rightmost bits fall off.
     ##
+    ## See also:
+    ## * `shr proc <#shr,int,SomeInteger>`_
+    ##
     ## .. code-block:: Nim
     ##   0b0001_0000'i8 shr 2 == 0b0000_0100'i8
     ##   0b1000_0000'i8 shr 8 == 0b1111_1111'i8
     ##   0b1000_0000'i8 shr 1 == 0b1100_0000'i8
+  proc ashr*(x: int8, y: SomeInteger): int8 {.magic: "AshrI", noSideEffect.}
+  proc ashr*(x: int16, y: SomeInteger): int16 {.magic: "AshrI", noSideEffect.}
+  proc ashr*(x: int32, y: SomeInteger): int32 {.magic: "AshrI", noSideEffect.}
+  proc ashr*(x: int64, y: SomeInteger): int64 {.magic: "AshrI", noSideEffect.}
 else:
   # used for bootstrapping the compiler
   proc ashr*[T](x: T, y: SomeInteger): T = discard
 
 proc `and`*(x, y: int): int {.magic: "BitandI", noSideEffect.}
+  ## Computes the `bitwise and` of numbers `x` and `y`.
+  ##
+  ## .. code-block:: Nim
+  ##   (0b0011 and 0b0101) == 0b0001
+  ##   (0b0111 and 0b1100) == 0b0100
 proc `and`*(x, y: int8): int8 {.magic: "BitandI", noSideEffect.}
 proc `and`*(x, y: int16): int16 {.magic: "BitandI", noSideEffect.}
 proc `and`*(x, y: int32): int32 {.magic: "BitandI", noSideEffect.}
 proc `and`*(x, y: int64): int64 {.magic: "BitandI", noSideEffect.}
-  ## computes the `bitwise and` of numbers `x` and `y`.
-  ##
-  ## .. code-block:: Nim
-  ##  (0xffff'i16 and 0x0010'i16) == 0x0010
 
 proc `or`*(x, y: int): int {.magic: "BitorI", noSideEffect.}
+  ## Computes the `bitwise or` of numbers `x` and `y`.
+  ##
+  ## .. code-block:: Nim
+  ##   (0b0011 or 0b0101) == 0b0111
+  ##   (0b0111 or 0b1100) == 0b1111
 proc `or`*(x, y: int8): int8 {.magic: "BitorI", noSideEffect.}
 proc `or`*(x, y: int16): int16 {.magic: "BitorI", noSideEffect.}
 proc `or`*(x, y: int32): int32 {.magic: "BitorI", noSideEffect.}
 proc `or`*(x, y: int64): int64 {.magic: "BitorI", noSideEffect.}
-  ## computes the `bitwise or` of numbers `x` and `y`.
-  ##
-  ## .. code-block:: Nim
-  ##  (0x0005'i16 or 0x0010'i16) == 0x0015
 
 proc `xor`*(x, y: int): int {.magic: "BitxorI", noSideEffect.}
+  ## Computes the `bitwise xor` of numbers `x` and `y`.
+  ##
+  ## .. code-block:: Nim
+  ##   (0b0011 xor 0b0101) == 0b0110
+  ##   (0b0111 xor 0b1100) == 0b1011
 proc `xor`*(x, y: int8): int8 {.magic: "BitxorI", noSideEffect.}
 proc `xor`*(x, y: int16): int16 {.magic: "BitxorI", noSideEffect.}
 proc `xor`*(x, y: int32): int32 {.magic: "BitxorI", noSideEffect.}
 proc `xor`*(x, y: int64): int64 {.magic: "BitxorI", noSideEffect.}
-  ## computes the `bitwise xor` of numbers `x` and `y`.
-  ##
-  ## .. code-block:: Nim
-  ##  (0x1011'i16 xor 0x0101'i16) == 0x1110
 
 proc `==`*(x, y: int): bool {.magic: "EqI", noSideEffect.}
+  ## Compares two integers for equality.
 proc `==`*(x, y: int8): bool {.magic: "EqI", noSideEffect.}
 proc `==`*(x, y: int16): bool {.magic: "EqI", noSideEffect.}
 proc `==`*(x, y: int32): bool {.magic: "EqI", noSideEffect.}
 proc `==`*(x, y: int64): bool {.magic: "EqI", noSideEffect.}
-  ## Compares two integers for equality.
 
 proc `<=`*(x, y: int): bool {.magic: "LeI", noSideEffect.}
+  ## Returns true if `x` is less than or equal to `y`.
 proc `<=`*(x, y: int8): bool {.magic: "LeI", noSideEffect.}
 proc `<=`*(x, y: int16): bool {.magic: "LeI", noSideEffect.}
 proc `<=`*(x, y: int32): bool {.magic: "LeI", noSideEffect.}
 proc `<=`*(x, y: int64): bool {.magic: "LeI", noSideEffect.}
-  ## Returns true iff `x` is less than or equal to `y`.
 
 proc `<`*(x, y: int): bool {.magic: "LtI", noSideEffect.}
+  ## Returns true if `x` is less than `y`.
 proc `<`*(x, y: int8): bool {.magic: "LtI", noSideEffect.}
 proc `<`*(x, y: int16): bool {.magic: "LtI", noSideEffect.}
 proc `<`*(x, y: int32): bool {.magic: "LtI", noSideEffect.}
 proc `<`*(x, y: int64): bool {.magic: "LtI", noSideEffect.}
-  ## Returns true iff `x` is less than `y`.
 
 type
   IntMax32 = int|int8|int16|int32
 
 proc `+%`*(x, y: IntMax32): IntMax32 {.magic: "AddU", noSideEffect.}
 proc `+%`*(x, y: int64): int64 {.magic: "AddU", noSideEffect.}
-  ## treats `x` and `y` as unsigned and adds them. The result is truncated to
-  ## fit into the result. This implements modulo arithmetic. No overflow
-  ## errors are possible.
+  ## Treats `x` and `y` as unsigned and adds them.
+  ##
+  ## The result is truncated to fit into the result.
+  ## This implements modulo arithmetic. No overflow errors are possible.
 
 proc `-%`*(x, y: IntMax32): IntMax32 {.magic: "SubU", noSideEffect.}
 proc `-%`*(x, y: int64): int64 {.magic: "SubU", noSideEffect.}
-  ## treats `x` and `y` as unsigned and subtracts them. The result is
-  ## truncated to fit into the result. This implements modulo arithmetic.
-  ## No overflow errors are possible.
+  ## Treats `x` and `y` as unsigned and subtracts them.
+  ##
+  ## The result is truncated to fit into the result.
+  ## This implements modulo arithmetic. No overflow errors are possible.
 
 proc `*%`*(x, y: IntMax32): IntMax32 {.magic: "MulU", noSideEffect.}
 proc `*%`*(x, y: int64): int64 {.magic: "MulU", noSideEffect.}
-  ## treats `x` and `y` as unsigned and multiplies them. The result is
-  ## truncated to fit into the result. This implements modulo arithmetic.
-  ## No overflow errors are possible.
+  ## Treats `x` and `y` as unsigned and multiplies them.
+  ##
+  ## The result is truncated to fit into the result.
+  ## This implements modulo arithmetic. No overflow errors are possible.
 
 proc `/%`*(x, y: IntMax32): IntMax32 {.magic: "DivU", noSideEffect.}
 proc `/%`*(x, y: int64): int64 {.magic: "DivU", noSideEffect.}
-  ## treats `x` and `y` as unsigned and divides them. The result is
-  ## truncated to fit into the result. This implements modulo arithmetic.
-  ## No overflow errors are possible.
+  ## Treats `x` and `y` as unsigned and divides them.
+  ##
+  ## The result is truncated to fit into the result.
+  ## This implements modulo arithmetic. No overflow errors are possible.
 
 proc `%%`*(x, y: IntMax32): IntMax32 {.magic: "ModU", noSideEffect.}
 proc `%%`*(x, y: int64): int64 {.magic: "ModU", noSideEffect.}
-  ## treats `x` and `y` as unsigned and compute the modulo of `x` and `y`.
+  ## Treats `x` and `y` as unsigned and compute the modulo of `x` and `y`.
+  ##
   ## The result is truncated to fit into the result.
-  ## This implements modulo arithmetic.
-  ## No overflow errors are possible.
+  ## This implements modulo arithmetic. No overflow errors are possible.
 
 proc `<=%`*(x, y: IntMax32): bool {.magic: "LeU", noSideEffect.}
 proc `<=%`*(x, y: int64): bool {.magic: "LeU64", noSideEffect.}
-  ## treats `x` and `y` as unsigned and compares them.
-  ## Returns true iff ``unsigned(x) <= unsigned(y)``.
+  ## Treats `x` and `y` as unsigned and compares them.
+  ## Returns true if ``unsigned(x) <= unsigned(y)``.
 
 proc `<%`*(x, y: IntMax32): bool {.magic: "LtU", noSideEffect.}
 proc `<%`*(x, y: int64): bool {.magic: "LtU64", noSideEffect.}
-  ## treats `x` and `y` as unsigned and compares them.
-  ## Returns true iff ``unsigned(x) < unsigned(y)``.
+  ## Treats `x` and `y` as unsigned and compares them.
+  ## Returns true if ``unsigned(x) < unsigned(y)``.
+
+template `>=%`*(x, y: untyped): untyped = y <=% x
+  ## Treats `x` and `y` as unsigned and compares them.
+  ## Returns true if ``unsigned(x) >= unsigned(y)``.
+
+template `>%`*(x, y: untyped): untyped = y <% x
+  ## Treats `x` and `y` as unsigned and compares them.
+  ## Returns true if ``unsigned(x) > unsigned(y)``.
+
 
 # unsigned integer operations:
 proc `not`*[T: SomeUnsignedInt](x: T): T {.magic: "BitnotI", noSideEffect.}
-  ## computes the `bitwise complement` of the integer `x`.
+  ## Computes the `bitwise complement` of the integer `x`.
 
 when defined(nimNewShiftOps):
   proc `shr`*[T: SomeUnsignedInt](x: T, y: SomeInteger): T {.magic: "ShrI", noSideEffect.}
-    ## computes the `shift right` operation of `x` and `y`.
-
+    ## Computes the `shift right` operation of `x` and `y`.
   proc `shl`*[T: SomeUnsignedInt](x: T, y: SomeInteger): T {.magic: "ShlI", noSideEffect.}
-    ## computes the `shift left` operation of `x` and `y`.
+    ## Computes the `shift left` operation of `x` and `y`.
 else:
   proc `shr`*[T: SomeUnsignedInt](x, y: T): T {.magic: "ShrI", noSideEffect.}
-    ## computes the `shift right` operation of `x` and `y`.
-
+    ## Computes the `shift right` operation of `x` and `y`.
   proc `shl`*[T: SomeUnsignedInt](x, y: T): T {.magic: "ShlI", noSideEffect.}
-    ## computes the `shift left` operation of `x` and `y`.
+    ## Computes the `shift left` operation of `x` and `y`.
 
 proc `and`*[T: SomeUnsignedInt](x, y: T): T {.magic: "BitandI", noSideEffect.}
-  ## computes the `bitwise and` of numbers `x` and `y`.
+  ## Computes the `bitwise and` of numbers `x` and `y`.
 
 proc `or`*[T: SomeUnsignedInt](x, y: T): T {.magic: "BitorI", noSideEffect.}
-  ## computes the `bitwise or` of numbers `x` and `y`.
+  ## Computes the `bitwise or` of numbers `x` and `y`.
 
 proc `xor`*[T: SomeUnsignedInt](x, y: T): T {.magic: "BitxorI", noSideEffect.}
-  ## computes the `bitwise xor` of numbers `x` and `y`.
+  ## Computes the `bitwise xor` of numbers `x` and `y`.
 
 proc `==`*[T: SomeUnsignedInt](x, y: T): bool {.magic: "EqI", noSideEffect.}
   ## Compares two unsigned integers for equality.
@@ -1232,25 +1474,18 @@ proc `*`*[T: SomeUnsignedInt](x, y: T): T {.magic: "MulU", noSideEffect.}
   ## Binary `*` operator for unsigned integers.
 
 proc `div`*[T: SomeUnsignedInt](x, y: T): T {.magic: "DivU", noSideEffect.}
-  ## computes the integer division. This is roughly the same as
-  ## ``trunc(x/y)``.
-  ##
-  ## .. code-block:: Nim
-  ##  (7 div 5) == 1
+  ## Computes the integer division for unsigned integers.
+  ## This is roughly the same as ``trunc(x/y)``.
 
 proc `mod`*[T: SomeUnsignedInt](x, y: T): T {.magic: "ModU", noSideEffect.}
-  ## computes the integer modulo operation (remainder).
-  ## This is the same as
-  ## ``x - (x div y) * y``.
-  ##
-  ## .. code-block:: Nim
-  ##   (7 mod 5) == 2
+  ## Computes the integer modulo operation (remainder) for unsigned integers.
+  ## This is the same as ``x - (x div y) * y``.
 
 proc `<=`*[T: SomeUnsignedInt](x, y: T): bool {.magic: "LeU", noSideEffect.}
-  ## Returns true iff ``x <= y``.
+  ## Returns true if ``x <= y``.
 
 proc `<`*[T: SomeUnsignedInt](x, y: T): bool {.magic: "LtU", noSideEffect.}
-  ## Returns true iff ``unsigned(x) < unsigned(y)``.
+  ## Returns true if ``unsigned(x) < unsigned(y)``.
 
 # floating point operations:
 proc `+`*(x: float32): float32 {.magic: "UnaryPlusF64", noSideEffect.}
@@ -1266,7 +1501,7 @@ proc `+`*(x, y: float): float {.magic: "AddF64", noSideEffect.}
 proc `-`*(x, y: float): float {.magic: "SubF64", noSideEffect.}
 proc `*`*(x, y: float): float {.magic: "MulF64", noSideEffect.}
 proc `/`*(x, y: float): float {.magic: "DivF64", noSideEffect.}
-  ## computes the floating point division
+  ## Computes the floating point division.
 
 proc `==`*(x, y: float32): bool {.magic: "EqF64", noSideEffect.}
 proc `<=`*(x, y: float32): bool {.magic: "LeF64", noSideEffect.}
@@ -1279,13 +1514,32 @@ proc `<`*(x, y: float): bool {.magic: "LtF64", noSideEffect.}
 # set operators
 proc `*`*[T](x, y: set[T]): set[T] {.magic: "MulSet", noSideEffect.}
   ## This operator computes the intersection of two sets.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = {1, 2, 3}
+  ##     b = {2, 3, 4}
+  ##   echo a * b # => {2, 3}
 proc `+`*[T](x, y: set[T]): set[T] {.magic: "PlusSet", noSideEffect.}
   ## This operator computes the union of two sets.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = {1, 2, 3}
+  ##     b = {2, 3, 4}
+  ##   echo a + b # => {1, 2, 3, 4}
 proc `-`*[T](x, y: set[T]): set[T] {.magic: "MinusSet", noSideEffect.}
-  ## This operator computes the difference of two sets.
+  ## This operator computes the diference of two sets.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = {1, 2, 3}
+  ##     b = {2, 3, 4}
+  ##   echo a - b # => {1}
 
 proc contains*[T](x: set[T], y: T): bool {.magic: "InSet", noSideEffect.}
   ## One should overload this proc if one wants to overload the ``in`` operator.
+  ##
   ## The parameters are in reverse order! ``a in b`` is a template for
   ## ``contains(b, a)``.
   ## This is because the unification algorithm that Nim uses for overload
@@ -1304,7 +1558,7 @@ proc contains*[T](x: set[T], y: T): bool {.magic: "InSet", noSideEffect.}
   ## passes its arguments in reverse order.
 
 proc contains*[U, V, W](s: HSlice[U, V], value: W): bool {.noSideEffect, inline.} =
-  ## Checks if `value` is within the range of `s`; returns true iff
+  ## Checks if `value` is within the range of `s`; returns true if
   ## `value >= s.a and value <= s.b`
   ##
   ## .. code-block:: Nim
@@ -1314,22 +1568,27 @@ proc contains*[U, V, W](s: HSlice[U, V], value: W): bool {.noSideEffect, inline.
   result = s.a <= value and value <= s.b
 
 template `in`*(x, y: untyped): untyped {.dirty.} = contains(y, x)
-  ## Sugar for contains
+  ## Sugar for `contains`.
   ##
   ## .. code-block:: Nim
   ##   assert(1 in (1..3) == true)
   ##   assert(5 in (1..3) == false)
 template `notin`*(x, y: untyped): untyped {.dirty.} = not contains(y, x)
-  ## Sugar for not containing
+  ## Sugar for `not contains`.
   ##
   ## .. code-block:: Nim
   ##   assert(1 notin (1..3) == false)
   ##   assert(5 notin (1..3) == true)
 
 proc `is`*[T, S](x: T, y: S): bool {.magic: "Is", noSideEffect.}
-  ## Checks if T is of the same type as S
+  ## Checks if `T` is of the same type as `S`.
+  ##
+  ## For a negated version, use `isnot <#isnot.t,untyped,untyped>`_.
   ##
   ## .. code-block:: Nim
+  ##   assert 42 is int
+  ##   assert @[1, 2] is seq
+  ##
   ##   proc test[T](a: T): int =
   ##     when (T is int):
   ##       return a
@@ -1339,17 +1598,21 @@ proc `is`*[T, S](x: T, y: S): bool {.magic: "Is", noSideEffect.}
   ##   assert(test[int](3) == 3)
   ##   assert(test[string]("xyz") == 0)
 template `isnot`*(x, y: untyped): untyped = not (x is y)
-  ## Negated version of `is`. Equivalent to ``not(x is y)``.
+  ## Negated version of `is <#is,T,S>`_. Equivalent to ``not(x is y)``.
+  ##
+  ## .. code-block:: Nim
+  ##   assert 42 isnot float
+  ##   assert @[1, 2] isnot enum
 
 when defined(nimV2) and not defined(nimscript):
   type owned*{.magic: "BuiltinType".}[T]
 
   proc new*[T](a: var owned(ref T)) {.magic: "New", noSideEffect.}
-    ## creates a new object of type ``T`` and returns a safe (traced)
+    ## Creates a new object of type ``T`` and returns a safe (traced)
     ## reference to it in ``a``.
 
   proc new*(t: typedesc): auto =
-    ## creates a new object of type ``T`` and returns a safe (traced)
+    ## Creates a new object of type ``T`` and returns a safe (traced)
     ## reference to it as result value.
     ##
     ## When ``T`` is a ref type then the resulting type will be ``T``,
@@ -1362,11 +1625,11 @@ when defined(nimV2) and not defined(nimscript):
     return r
 else:
   proc new*[T](a: var ref T) {.magic: "New", noSideEffect.}
-    ## creates a new object of type ``T`` and returns a safe (traced)
+    ## Creates a new object of type ``T`` and returns a safe (traced)
     ## reference to it in ``a``.
 
   proc new*(t: typedesc): auto =
-    ## creates a new object of type ``T`` and returns a safe (traced)
+    ## Creates a new object of type ``T`` and returns a safe (traced)
     ## reference to it as result value.
     ##
     ## When ``T`` is a ref type then the resulting type will be ``T``,
@@ -1381,89 +1644,116 @@ else:
 proc `of`*[T, S](x: typeDesc[T], y: typeDesc[S]): bool {.magic: "Of", noSideEffect.}
 proc `of`*[T, S](x: T, y: typeDesc[S]): bool {.magic: "Of", noSideEffect.}
 proc `of`*[T, S](x: T, y: S): bool {.magic: "Of", noSideEffect.}
-  ## Checks if `x` has a type of `y`
+  ## Checks if `x` has a type of `y`.
   ##
   ## .. code-block:: Nim
   ##   assert(FloatingPointError of Exception)
   ##   assert(DivByZeroError of Exception)
 
 proc cmp*[T](x, y: T): int {.procvar.} =
-  ## Generic compare proc. Returns a value < 0 iff x < y, a value > 0 iff x > y
-  ## and 0 iff x == y. This is useful for writing generic algorithms without
-  ## performance loss. This generic implementation uses the `==` and `<`
-  ## operators.
+  ## Generic compare proc.
+  ##
+  ## Returns:
+  ## * a value less than zero, if `x < y`
+  ## * a value greater than zero, if `x > y`
+  ## * zero, if `x == y`
+  ##
+  ## This is useful for writing generic algorithms without performance loss.
+  ## This generic implementation uses the `==` and `<` operators.
   ##
   ## .. code-block:: Nim
   ##  import algorithm
-  ##  echo sorted(@[4,2,6,5,8,7], cmp[int])
+  ##  echo sorted(@[4, 2, 6, 5, 8, 7], cmp[int])
   if x == y: return 0
   if x < y: return -1
   return 1
 
 proc cmp*(x, y: string): int {.noSideEffect, procvar.}
   ## Compare proc for strings. More efficient than the generic version.
+  ##
   ## **Note**: The precise result values depend on the used C runtime library and
   ## can differ between operating systems!
 
 proc `@`* [IDX, T](a: array[IDX, T]): seq[T] {.
   magic: "ArrToSeq", nosideeffect.}
-  ## turns an array into a sequence. This most often useful for constructing
+  ## Turns an array into a sequence.
+  ##
+  ## This most often useful for constructing
   ## sequences with the array constructor: ``@[1, 2, 3]`` has the type
   ## ``seq[int]``, while ``[1, 2, 3]`` has the type ``array[0..2, int]``.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = [1, 3, 5]
+  ##     b = "foo"
+  ##
+  ##   echo @a # => @[1, 3, 5]
+  ##   echo @b # => @['f', 'o', 'o']
 
 proc setLen*[T](s: var seq[T], newlen: Natural) {.
   magic: "SetLengthSeq", noSideEffect.}
-  ## sets the length of `s` to `newlen`.
-  ## ``T`` may be any sequence type.
+  ## Sets the length of seq `s` to `newlen`. ``T`` may be any sequence type.
+  ##
   ## If the current length is greater than the new length,
   ## ``s`` will be truncated.
+  ##
+  ## .. code-block:: Nim
+  ##   var x = @[10, 20]
+  ##   x.setLen(5)
+  ##   x[4] = 50
+  ##   assert x == @[10, 20, 0, 0, 50]
+  ##   x.setLen(1)
+  ##   assert x == @[10]
 
 proc setLen*(s: var string, newlen: Natural) {.
   magic: "SetLengthStr", noSideEffect.}
-  ## sets the length of `s` to `newlen`.
+  ## Sets the length of string `s` to `newlen`.
+  ##
   ## If the current length is greater than the new length,
   ## ``s`` will be truncated.
   ##
   ## .. code-block:: Nim
   ##  var myS = "Nim is great!!"
-  ##  myS.setLen(3)
+  ##  myS.setLen(3) # myS <- "Nim"
   ##  echo myS, " is fantastic!!"
 
 proc newString*(len: Natural): string {.
   magic: "NewString", importc: "mnewString", noSideEffect.}
-  ## returns a new string of length ``len`` but with uninitialized
+  ## Returns a new string of length ``len`` but with uninitialized
   ## content. One needs to fill the string character after character
-  ## with the index operator ``s[i]``. This procedure exists only for
-  ## optimization purposes; the same effect can be achieved with the
-  ## ``&`` operator or with ``add``.
+  ## with the index operator ``s[i]``.
+  ##
+  ## This procedure exists only for optimization purposes;
+  ## the same effect can be achieved with the ``&`` operator or with ``add``.
 
 proc newStringOfCap*(cap: Natural): string {.
   magic: "NewStringOfCap", importc: "rawNewString", noSideEffect.}
-  ## returns a new string of length ``0`` but with capacity `cap`.This
-  ## procedure exists only for optimization purposes; the same effect can
+  ## Returns a new string of length ``0`` but with capacity `cap`.
+  ##
+  ## This procedure exists only for optimization purposes; the same effect can
   ## be achieved with the ``&`` operator or with ``add``.
 
 proc `&`*(x: string, y: char): string {.
   magic: "ConStrStr", noSideEffect, merge.}
-  ## Concatenates `x` with `y`
+  ## Concatenates `x` with `y`.
   ##
   ## .. code-block:: Nim
   ##   assert("ab" & 'c' == "abc")
 proc `&`*(x, y: char): string {.
   magic: "ConStrStr", noSideEffect, merge.}
-  ## Concatenates `x` and `y` into a string
+  ## Concatenates `x` and `y` into a string.
   ##
   ## .. code-block:: Nim
   ##   assert('a' & 'b' == "ab")
 proc `&`*(x, y: string): string {.
   magic: "ConStrStr", noSideEffect, merge.}
-  ## Concatenates `x` and `y`
+  ## Concatenates `x` and `y`.
   ##
   ## .. code-block:: Nim
   ##   assert("ab" & "cd" == "abcd")
 proc `&`*(x: char, y: string): string {.
   magic: "ConStrStr", noSideEffect, merge.}
-  ## Concatenates `x` with `y`
+  ## Concatenates `x` with `y`.
   ##
   ## .. code-block:: Nim
   ##   assert('a' & "bc" == "abc")
@@ -1472,7 +1762,7 @@ proc `&`*(x: char, y: string): string {.
 # that the merge optimization works properly.
 
 proc add*(x: var string, y: char) {.magic: "AppendStrCh", noSideEffect.}
-  ## Appends `y` to `x` in place
+  ## Appends `y` to `x` in place.
   ##
   ## .. code-block:: Nim
   ##   var tmp = ""
@@ -1480,7 +1770,7 @@ proc add*(x: var string, y: char) {.magic: "AppendStrCh", noSideEffect.}
   ##   tmp.add('b')
   ##   assert(tmp == "ab")
 proc add*(x: var string, y: string) {.magic: "AppendStrStr", noSideEffect.}
-  ## Concatenates `x` and `y` in place
+  ## Concatenates `x` and `y` in place.
   ##
   ## .. code-block:: Nim
   ##   var tmp = ""
@@ -1490,37 +1780,41 @@ proc add*(x: var string, y: string) {.magic: "AppendStrStr", noSideEffect.}
 
 
 type
-  Endianness* = enum ## is a type describing the endianness of a processor.
+  Endianness* = enum ## Type describing the endianness of a processor.
     littleEndian, bigEndian
 
 const
   isMainModule* {.magic: "IsMainModule".}: bool = false
-    ## is true only when accessed in the main module. This works thanks to
+    ## True only when accessed in the main module. This works thanks to
     ## compiler magic. It is useful to embed testing code in a module.
 
   CompileDate* {.magic: "CompileDate"}: string = "0000-00-00"
-    ## is the date (in UTC) of compilation as a string of the form
+    ## The date (in UTC) of compilation as a string of the form
     ## ``YYYY-MM-DD``. This works thanks to compiler magic.
 
   CompileTime* {.magic: "CompileTime"}: string = "00:00:00"
-    ## is the time (in UTC) of compilation as a string of the form
+    ## The time (in UTC) of compilation as a string of the form
     ## ``HH:MM:SS``. This works thanks to compiler magic.
 
   cpuEndian* {.magic: "CpuEndian"}: Endianness = littleEndian
-    ## is the endianness of the target CPU. This is a valuable piece of
+    ## The endianness of the target CPU. This is a valuable piece of
     ## information for low-level code only. This works thanks to compiler
     ## magic.
 
   hostOS* {.magic: "HostOS".}: string = ""
-    ## a string that describes the host operating system. Possible values:
-    ## "windows", "macosx", "linux", "netbsd", "freebsd", "openbsd", "solaris",
-    ## "aix", "haiku", "standalone".
+    ## A string that describes the host operating system.
+    ##
+    ## Possible values:
+    ## `"windows"`, `"macosx"`, `"linux"`, `"netbsd"`, `"freebsd"`,
+    ## `"openbsd"`, `"solaris"`, `"aix"`, `"haiku"`, `"standalone"`.
 
   hostCPU* {.magic: "HostCPU".}: string = ""
-    ## a string that describes the host CPU. Possible values:
-    ## "i386", "alpha", "powerpc", "powerpc64", "powerpc64el", "sparc",
-    ## "amd64", "mips", "mipsel", "arm", "arm64", "mips64", "mips64el",
-    ## "riscv64".
+    ## A string that describes the host CPU.
+    ##
+    ## Possible values:
+    ## `"i386"`, `"alpha"`, `"powerpc"`, `"powerpc64"`, `"powerpc64el"`,
+    ## `"sparc"`, `"amd64"`, `"mips"`, `"mipsel"`, `"arm"`, `"arm64"`,
+    ## `"mips64"`, `"mips64el"`, `"riscv64"`.
 
   seqShallowFlag = low(int)
   strlitFlag = 1 shl (sizeof(int)*8 - 2) # later versions of the codegen \
@@ -1529,23 +1823,23 @@ const
 
 {.push profiler: off.}
 let nimvm* {.magic: "Nimvm", compileTime.}: bool = false
-  ## may be used only in "when" expression.
-  ## It is true in Nim VM context and false otherwise
+  ## May be used only in `when` expression.
+  ## It is true in Nim VM context and false otherwise.
 {.pop.}
 
 proc compileOption*(option: string): bool {.
   magic: "CompileOption", noSideEffect.}
-  ## can be used to determine an on|off compile-time option. Example:
+  ## Can be used to determine an `on|off` compile-time option. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   when compileOption("floatchecks"):
   ##     echo "compiled with floating point NaN and Inf checks"
 
 proc compileOption*(option, arg: string): bool {.
   magic: "CompileOptionArg", noSideEffect.}
-  ## can be used to determine an enum compile-time option. Example:
+  ## Can be used to determine an enum compile-time option. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   when compileOption("opt", "size") and compileOption("gc", "boehm"):
   ##     echo "compiled with optimization for size and uses Boehm's GC"
 
@@ -1569,7 +1863,7 @@ when defined(boehmgc):
   {.pragma: boehmGC, noconv, dynlib: boehmLib.}
 
 when taintMode:
-  type TaintedString* = distinct string ## a distinct string type that
+  type TaintedString* = distinct string ## A distinct string type that
                                         ## is `tainted`:idx:, see `taint mode
                                         ## <manual.html#taint-mode>`_ for
                                         ## details. It is an alias for
@@ -1578,7 +1872,7 @@ when taintMode:
 
   proc len*(s: TaintedString): int {.borrow.}
 else:
-  type TaintedString* = string          ## a distinct string type that
+  type TaintedString* = string          ## A distinct string type that
                                         ## is `tainted`:idx:, see `taint mode
                                         ## <manual.html#taint-mode>`_ for
                                         ## details. It is an alias for
@@ -1606,16 +1900,16 @@ when defined(nodejs) and not defined(nimscript):
   programResult = 0
 else:
   var programResult* {.compilerproc, exportc: "nim_program_result".}: int
-    ## modify this variable to specify the exit code of the program
+    ## Modify this variable to specify the exit code of the program
     ## under normal circumstances. When the program is terminated
-    ## prematurely using ``quit``, this value is ignored.
+    ## prematurely using `quit proc <#quit,int>`_, this value is ignored.
 
 when defined(nimdoc):
   proc quit*(errorcode: int = QuitSuccess) {.magic: "Exit", noreturn.}
     ## Stops the program immediately with an exit code.
     ##
     ## Before stopping the program the "quit procedures" are called in the
-    ## opposite order they were added with `addQuitProc <#addQuitProc>`_.
+    ## opposite order they were added with `addQuitProc <#addQuitProc,proc>`_.
     ## ``quit`` never returns and ignores any exception that may have been raised
     ## by the quit procedures.  It does *not* call the garbage collector to free
     ## all the memory, unless a quit procedure calls `GC_fullCollect
@@ -1672,43 +1966,66 @@ when not defined(JS) and not defined(nimscript) and hasAlloc and not defined(gcD
 
 when defined(gcDestructors):
   proc add*[T](x: var seq[T], y: sink T) {.magic: "AppendSeqElem", noSideEffect.} =
+    ## Generic proc for adding a data item `y` to a container `x`.
+    ##
+    ## For containers that have an order, `add` means *append*. New generic
+    ## containers should also call their adding proc `add` for consistency.
+    ## Generic code becomes much easier to write if the Nim naming scheme is
+    ## respected.
     let xl = x.len
     setLen(x, xl + 1)
     x[xl] = y
 else:
   proc add*[T](x: var seq[T], y: T) {.magic: "AppendSeqElem", noSideEffect.}
+    ## Generic proc for adding a data item `y` to a container `x`.
+    ##
+    ## For containers that have an order, `add` means *append*. New generic
+    ## containers should also call their adding proc `add` for consistency.
+    ## Generic code becomes much easier to write if the Nim naming scheme is
+    ## respected.
+
 proc add*[T](x: var seq[T], y: openArray[T]) {.noSideEffect.} =
-  ## Generic proc for adding a data item `y` to a container `x`.
+  ## Generic proc for adding a container `y` to a container `x`.
+  ##
   ## For containers that have an order, `add` means *append*. New generic
   ## containers should also call their adding proc `add` for consistency.
   ## Generic code becomes much easier to write if the Nim naming scheme is
   ## respected.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `& proc <#&,seq[T][T],seq[T][T]>`_
+  ##
+  ## .. code-block:: Nim
   ##   var s: seq[string] = @["test2","test2"]
-  ##   s.add("test") #=> @[test2, test2, test]
+  ##   s.add("test") # s <- @[test2, test2, test]
   let xl = x.len
   setLen(x, xl + y.len)
   for i in 0..high(y): x[xl+i] = y[i]
 
 proc del*[T](x: var seq[T], i: Natural) {.noSideEffect.} =
-  ## deletes the item at index `i` by putting ``x[high(x)]`` into position `i`.
+  ## Deletes the item at index `i` by putting ``x[high(x)]`` into position `i`.
   ## This is an O(1) operation.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `delete <#delete,seq[T][T],Natural>`_ for preserving the order
+  ##
+  ## .. code-block:: Nim
   ##  var i = @[1, 2, 3, 4, 5]
-  ##  i.del(2) #=> @[1, 2, 5, 4]
+  ##  i.del(2) # => @[1, 2, 5, 4]
   let xl = x.len - 1
   shallowCopy(x[i], x[xl])
   setLen(x, xl)
 
 proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} =
-  ## deletes the item at index `i` by moving ``x[i+1..]`` by one position.
+  ## Deletes the item at index `i` by moving ``x[i+1..]`` by one position.
   ## This is an O(n) operation.
   ##
-  ## .. code-block:: nim
+  ## See also:
+  ## * `del <#delete,seq[T][T],Natural>`_ for O(1) operation
+  ##
+  ## .. code-block:: Nim
   ##  var i = @[1, 2, 3, 4, 5]
-  ##  i.delete(2) #=> @[1, 2, 4, 5]
+  ##  i.delete(2) # => @[1, 2, 4, 5]
   template defaultImpl =
     let xl = x.len
     for j in i.int..xl-2: shallowCopy(x[j], x[j+1])
@@ -1723,11 +2040,11 @@ proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} =
       defaultImpl()
 
 proc insert*[T](x: var seq[T], item: T, i = 0.Natural) {.noSideEffect.} =
-  ## inserts `item` into `x` at position `i`.
+  ## Inserts `item` into `x` at position `i`.
   ##
-  ## .. code-block:: nim
-  ##  var i = @[1, 2, 3, 4, 5]
-  ##  i.insert(2, 4) #=> @[1, 2, 3, 4, 2, 5]
+  ## .. code-block:: Nim
+  ##  var i = @[1, 3, 5]
+  ##  i.insert(99, 0) # i <- @[99, 1, 3, 5]
   template defaultImpl =
     let xl = x.len
     setLen(x, xl+1)
@@ -1746,15 +2063,16 @@ proc insert*[T](x: var seq[T], item: T, i = 0.Natural) {.noSideEffect.} =
   x[i] = item
 
 proc repr*[T](x: T): string {.magic: "Repr", noSideEffect.}
-  ## takes any Nim variable and returns its string representation. It
-  ## works even for complex data graphs with cycles. This is a great
+  ## Takes any Nim variable and returns its string representation.
+  ##
+  ## It works even for complex data graphs with cycles. This is a great
   ## debugging tool.
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##  var s: seq[string] = @["test2", "test2"]
   ##  var i = @[1, 2, 3, 4, 5]
-  ##  repr(s) #=> 0x1055eb050[0x1055ec050"test2", 0x1055ec078"test2"]
-  ##  repr(i) #=> 0x1055ed050[1, 2, 3, 4, 5]
+  ##  echo repr(s) # => 0x1055eb050[0x1055ec050"test2", 0x1055ec078"test2"]
+  ##  echo repr(i) # => 0x1055ed050[1, 2, 3, 4, 5]
 
 type
   ByteAddress* = int
@@ -1828,41 +2146,51 @@ type # these work for most platforms:
   cstringArray* {.importc: "char**", nodecl.} = ptr UncheckedArray[cstring]
     ## This is binary compatible to the type ``char**`` in *C*. The array's
     ## high value is large enough to disable bounds checking in practice.
-    ## Use `cstringArrayToSeq` to convert it into a ``seq[string]``.
+    ## Use `cstringArrayToSeq proc <#cstringArrayToSeq,cstringArray,Natural>`_
+    ## to convert it into a ``seq[string]``.
 
-  PFloat32* = ptr float32 ## an alias for ``ptr float32``
-  PFloat64* = ptr float64 ## an alias for ``ptr float64``
-  PInt64* = ptr int64 ## an alias for ``ptr int64``
-  PInt32* = ptr int32 ## an alias for ``ptr int32``
+  PFloat32* = ptr float32    ## An alias for ``ptr float32``.
+  PFloat64* = ptr float64    ## An alias for ``ptr float64``.
+  PInt64* = ptr int64        ## An alias for ``ptr int64``.
+  PInt32* = ptr int32        ## An alias for ``ptr int32``.
 
 proc toFloat*(i: int): float {.
   magic: "ToFloat", noSideEffect, importc: "toFloat".}
-  ## converts an integer `i` into a ``float``. If the conversion
-  ## fails, `ValueError` is raised. However, on most platforms the
-  ## conversion cannot fail.
+  ## Converts an integer `i` into a ``float``.
+  ##
+  ## If the conversion fails, `ValueError` is raised.
+  ## However, on most platforms the conversion cannot fail.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = 2
+  ##     b = 3.7
+  ##
+  ##   echo a.toFloat + b # => 5.7
 
 proc toBiggestFloat*(i: BiggestInt): BiggestFloat {.
   magic: "ToBiggestFloat", noSideEffect, importc: "toBiggestFloat".}
-  ## converts a biggestint `i` into a ``biggestfloat``. If the conversion
-  ## fails, `ValueError` is raised. However, on most platforms the
-  ## conversion cannot fail.
+  ## Same as `toFloat <#toFloat,int>`_ but for ``BiggestInt`` to ``BiggestFloat``.
 
 proc toInt*(f: float): int {.
-  magic: "ToInt", noSideEffect, importc: "toInt".} =
-  ## converts a floating point number `f` into an ``int``. Conversion
-  ## rounds `f` half away from 0, see https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero
+  magic: "ToInt", noSideEffect, importc: "toInt".}
+  ## Converts a floating point number `f` into an ``int``.
+  ##
+  ## Conversion rounds `f` half away from 0, see
+  ## `Round half away from zero
+  ## <https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero>`_.
+  ##
   ## Note that some floating point numbers (e.g. infinity or even 1e19)
   ## cannot be accurately converted.
-  runnableExamples:
-    doAssert toInt(0.49) == 0
-    doAssert toInt(0.5) == 1
-    doAssert toInt(-0.5) == -1 ## rounding is symmetrical
+  ##
+  ## .. code-block:: Nim
+  ##   doAssert toInt(0.49) == 0
+  ##   doAssert toInt(0.5) == 1
+  ##   doAssert toInt(-0.5) == -1 # rounding is symmetrical
 
 proc toBiggestInt*(f: BiggestFloat): BiggestInt {.
-  magic: "ToBiggestInt", noSideEffect, importc: "toBiggestInt".} =
-  ## Same as `toInt` but for BiggestFloat to ``BiggestInt``.
-  runnableExamples:
-    doAssert toBiggestInt(0.49) == 0
+  magic: "ToBiggestInt", noSideEffect, importc: "toBiggestInt".}
+  ## Same as `toInt <#toInt,float>`_ but for ``BiggestFloat`` to ``BiggestInt``.
 
 proc addQuitProc*(quitProc: proc() {.noconv.}) {.
   importc: "atexit", header: "<stdlib.h>".}
@@ -1880,148 +2208,234 @@ proc addQuitProc*(quitProc: proc() {.noconv.}) {.
 
 when not defined(nimscript) and not defined(JS):
   proc zeroMem*(p: pointer, size: Natural) {.inline, benign.}
-    ## overwrites the contents of the memory at ``p`` with the value 0.
+    ## Overwrites the contents of the memory at ``p`` with the value 0.
+    ##
     ## Exactly ``size`` bytes will be overwritten. Like any procedure
-    ## dealing with raw memory this is *unsafe*.
+    ## dealing with raw memory this is **unsafe**.
 
   proc copyMem*(dest, source: pointer, size: Natural) {.inline, benign,
     tags: [], locks: 0.}
-    ## copies the contents from the memory at ``source`` to the memory
-    ## at ``dest``. Exactly ``size`` bytes will be copied. The memory
+    ## Copies the contents from the memory at ``source`` to the memory
+    ## at ``dest``.
+    ## Exactly ``size`` bytes will be copied. The memory
     ## regions may not overlap. Like any procedure dealing with raw
-    ## memory this is *unsafe*.
+    ## memory this is **unsafe**.
 
   proc moveMem*(dest, source: pointer, size: Natural) {.inline, benign,
     tags: [], locks: 0.}
-    ## copies the contents from the memory at ``source`` to the memory
-    ## at ``dest``. Exactly ``size`` bytes will be copied. The memory
+    ## Copies the contents from the memory at ``source`` to the memory
+    ## at ``dest``.
+    ##
+    ## Exactly ``size`` bytes will be copied. The memory
     ## regions may overlap, ``moveMem`` handles this case appropriately
     ## and is thus somewhat more safe than ``copyMem``. Like any procedure
-    ## dealing with raw memory this is still *unsafe*, though.
+    ## dealing with raw memory this is still **unsafe**, though.
 
   proc equalMem*(a, b: pointer, size: Natural): bool {.inline, noSideEffect, tags: [], locks: 0.}
-    ## compares the memory blocks ``a`` and ``b``. ``size`` bytes will
-    ## be compared. If the blocks are equal, true is returned, false
+    ## Compares the memory blocks ``a`` and ``b``. ``size`` bytes will
+    ## be compared.
+    ##
+    ## If the blocks are equal, `true` is returned, `false`
     ## otherwise. Like any procedure dealing with raw memory this is
-    ## *unsafe*.
+    ## **unsafe**.
 
 when not defined(nimscript):
   when hasAlloc:
     proc alloc*(size: Natural): pointer {.noconv, rtl, tags: [], benign, raises: [].}
-      ## allocates a new memory block with at least ``size`` bytes. The
-      ## block has to be freed with ``realloc(block, 0)`` or
-      ## ``dealloc(block)``. The block is not initialized, so reading
+      ## Allocates a new memory block with at least ``size`` bytes.
+      ##
+      ## The block has to be freed with `realloc(block, 0) <#realloc,pointer,Natural>`_
+      ## or `dealloc(block) <#dealloc,pointer>`_.
+      ## The block is not initialized, so reading
       ## from it before writing to it is undefined behaviour!
+      ##
       ## The allocated memory belongs to its allocating thread!
-      ## Use `allocShared` to allocate from a shared heap.
+      ## Use `allocShared <#allocShared,Natural>`_ to allocate from a shared heap.
+      ##
+      ## See also:
+      ## * `alloc0 <#alloc0,Natural>`_
     proc createU*(T: typedesc, size = 1.Positive): ptr T {.inline, benign, raises: [].} =
-      ## allocates a new memory block with at least ``T.sizeof * size``
-      ## bytes. The block has to be freed with ``resize(block, 0)`` or
-      ## ``dealloc(block)``. The block is not initialized, so reading
+      ## Allocates a new memory block with at least ``T.sizeof * size`` bytes.
+      ##
+      ## The block has to be freed with `resize(block, 0) <#resize,ptr.T,Natural>`_
+      ## or `dealloc(block) <#dealloc,pointer>`_.
+      ## The block is not initialized, so reading
       ## from it before writing to it is undefined behaviour!
+      ##
       ## The allocated memory belongs to its allocating thread!
-      ## Use `createSharedU` to allocate from a shared heap.
+      ## Use `createSharedU <#createSharedU,typedesc>`_ to allocate from a shared heap.
+      ##
+      ## See also:
+      ## * `create <#create,typedesc>`_
       cast[ptr T](alloc(T.sizeof * size))
+
     proc alloc0*(size: Natural): pointer {.noconv, rtl, tags: [], benign, raises: [].}
-      ## allocates a new memory block with at least ``size`` bytes. The
-      ## block has to be freed with ``realloc(block, 0)`` or
-      ## ``dealloc(block)``. The block is initialized with all bytes
-      ## containing zero, so it is somewhat safer than ``alloc``.
+      ## Allocates a new memory block with at least ``size`` bytes.
+      ##
+      ## The block has to be freed with `realloc(block, 0) <#realloc,pointer,Natural>`_
+      ## or `dealloc(block) <#dealloc,pointer>`_.
+      ## The block is initialized with all bytes containing zero, so it is
+      ## somewhat safer than  `alloc <#alloc,Natural>`_.
+      ##
       ## The allocated memory belongs to its allocating thread!
-      ## Use `allocShared0` to allocate from a shared heap.
+      ## Use `allocShared0 <#allocShared0,Natural>`_ to allocate from a shared heap.
     proc create*(T: typedesc, size = 1.Positive): ptr T {.inline, benign, raises: [].} =
-      ## allocates a new memory block with at least ``T.sizeof * size``
-      ## bytes. The block has to be freed with ``resize(block, 0)`` or
-      ## ``dealloc(block)``. The block is initialized with all bytes
-      ## containing zero, so it is somewhat safer than ``createU``.
+      ## Allocates a new memory block with at least ``T.sizeof * size`` bytes.
+      ##
+      ## The block has to be freed with `resize(block, 0) <#resize,ptr.T,Natural>`_
+      ## or `dealloc(block) <#dealloc,pointer>`_.
+      ## The block is initialized with all bytes containing zero, so it is
+      ## somewhat safer than `createU <#createU,typedesc>`_.
+      ##
       ## The allocated memory belongs to its allocating thread!
-      ## Use `createShared` to allocate from a shared heap.
+      ## Use `createShared <#createShared,typedesc>`_ to allocate from a shared heap.
       cast[ptr T](alloc0(sizeof(T) * size))
+
     proc realloc*(p: pointer, newSize: Natural): pointer {.noconv, rtl, tags: [],
                                                            benign, raises: [].}
-      ## grows or shrinks a given memory block. If p is **nil** then a new
-      ## memory block is returned. In either way the block has at least
-      ## ``newSize`` bytes. If ``newSize == 0`` and p is not **nil**
-      ## ``realloc`` calls ``dealloc(p)``. In other cases the block has to
-      ## be freed with ``dealloc``.
+      ## Grows or shrinks a given memory block.
+      ##
+      ## If `p` is **nil** then a new memory block is returned.
+      ## In either way the block has at least ``newSize`` bytes.
+      ## If ``newSize == 0`` and `p` is not **nil** ``realloc`` calls ``dealloc(p)``.
+      ## In other cases the block has to be freed with
+      ## `dealloc(block) <#dealloc,pointer>`_.
+      ##
       ## The allocated memory belongs to its allocating thread!
-      ## Use `reallocShared` to reallocate from a shared heap.
+      ## Use `reallocShared <#reallocShared,pointer,Natural>`_ to reallocate
+      ## from a shared heap.
     proc resize*[T](p: ptr T, newSize: Natural): ptr T {.inline, benign, raises: [].} =
-      ## grows or shrinks a given memory block. If p is **nil** then a new
-      ## memory block is returned. In either way the block has at least
-      ## ``T.sizeof * newSize`` bytes. If ``newSize == 0`` and p is not
-      ## **nil** ``resize`` calls ``dealloc(p)``. In other cases the block
-      ## has to be freed with ``free``. The allocated memory belongs to
-      ## its allocating thread!
-      ## Use `resizeShared` to reallocate from a shared heap.
+      ## Grows or shrinks a given memory block.
+      ##
+      ## If `p` is **nil** then a new memory block is returned.
+      ## In either way the block has at least ``T.sizeof * newSize`` bytes.
+      ## If ``newSize == 0`` and `p` is not **nil** ``resize`` calls ``dealloc(p)``.
+      ## In other cases the block has to be freed with ``free``.
+      ##
+      ## The allocated memory belongs to its allocating thread!
+      ## Use `resizeShared <#resizeShared,ptr.T,Natural>`_ to reallocate
+      ## from a shared heap.
       cast[ptr T](realloc(p, T.sizeof * newSize))
+
     proc dealloc*(p: pointer) {.noconv, rtl, tags: [], benign, raises: [].}
-      ## frees the memory allocated with ``alloc``, ``alloc0`` or
-      ## ``realloc``. This procedure is dangerous! If one forgets to
-      ## free the memory a leak occurs; if one tries to access freed
-      ## memory (or just freeing it twice!) a core dump may happen
+      ## Frees the memory allocated with ``alloc``, ``alloc0`` or
+      ## ``realloc``.
+      ##
+      ## **This procedure is dangerous!**
+      ## If one forgets to free the memory a leak occurs; if one tries to
+      ## access freed memory (or just freeing it twice!) a core dump may happen
       ## or other memory may be corrupted.
+      ##
       ## The freed memory must belong to its allocating thread!
-      ## Use `deallocShared` to deallocate from a shared heap.
+      ## Use `deallocShared <#deallocShared,pointer>`_ to deallocate from a shared heap.
 
     proc allocShared*(size: Natural): pointer {.noconv, rtl, benign, raises: [].}
-      ## allocates a new memory block on the shared heap with at
-      ## least ``size`` bytes. The block has to be freed with
-      ## ``reallocShared(block, 0)`` or ``deallocShared(block)``. The block
-      ## is not initialized, so reading from it before writing to it is
-      ## undefined behaviour!
+      ## Allocates a new memory block on the shared heap with at
+      ## least ``size`` bytes.
+      ##
+      ## The block has to be freed with
+      ## `reallocShared(block, 0) <#reallocShared,pointer,Natural>`_
+      ## or `deallocShared(block) <#deallocShared,pointer>`_.
+      ##
+      ## The block is not initialized, so reading from it before writing
+      ## to it is undefined behaviour!
+      ##
+      ## See also:
+      ## `allocShared0 <#allocShared0,Natural>`_.
     proc createSharedU*(T: typedesc, size = 1.Positive): ptr T {.inline,
                                                                  benign, raises: [].} =
-      ## allocates a new memory block on the shared heap with at
-      ## least ``T.sizeof * size`` bytes. The block has to be freed with
-      ## ``resizeShared(block, 0)`` or ``freeShared(block)``. The block
-      ## is not initialized, so reading from it before writing to it is
-      ## undefined behaviour!
+      ## Allocates a new memory block on the shared heap with at
+      ## least ``T.sizeof * size`` bytes.
+      ##
+      ## The block has to be freed with
+      ## `resizeShared(block, 0) <#resizeShared,ptr.T,Natural>`_ or
+      ## `freeShared(block) <#freeShared,ptr.T>`_.
+      ##
+      ## The block is not initialized, so reading from it before writing
+      ## to it is undefined behaviour!
+      ##
+      ## See also:
+      ## * `createShared <#createShared,typedesc>`_
       cast[ptr T](allocShared(T.sizeof * size))
+
     proc allocShared0*(size: Natural): pointer {.noconv, rtl, benign, raises: [].}
-      ## allocates a new memory block on the shared heap with at
-      ## least ``size`` bytes. The block has to be freed with
-      ## ``reallocShared(block, 0)`` or ``deallocShared(block)``.
+      ## Allocates a new memory block on the shared heap with at
+      ## least ``size`` bytes.
+      ##
+      ## The block has to be freed with
+      ## `reallocShared(block, 0) <#reallocShared,pointer,Natural>`_
+      ## or `deallocShared(block) <#deallocShared,pointer>`_.
+      ##
       ## The block is initialized with all bytes
-      ## containing zero, so it is somewhat safer than ``allocShared``.
-    proc createShared*(T: typedesc, size = 1.Positive): ptr T {.inline, raises: [].} =
-      ## allocates a new memory block on the shared heap with at
-      ## least ``T.sizeof * size`` bytes. The block has to be freed with
-      ## ``resizeShared(block, 0)`` or ``freeShared(block)``.
+      ## containing zero, so it is somewhat safer than
+      ## `allocShared <#allocShared,Natural>`_.
+    proc createShared*(T: typedesc, size = 1.Positive): ptr T {.inline.} =
+      ## Allocates a new memory block on the shared heap with at
+      ## least ``T.sizeof * size`` bytes.
+      ##
+      ## The block has to be freed with
+      ## `resizeShared(block, 0) <#resizeShared,ptr.T,Natural>`_ or
+      ## `freeShared(block) <#freeShared,ptr.T>`_.
+      ##
       ## The block is initialized with all bytes
-      ## containing zero, so it is somewhat safer than ``createSharedU``.
+      ## containing zero, so it is somewhat safer than
+      ## `createSharedU <#createSharedU,typedesc>`_.
       cast[ptr T](allocShared0(T.sizeof * size))
+
     proc reallocShared*(p: pointer, newSize: Natural): pointer {.noconv, rtl,
                                                                  benign, raises: [].}
-      ## grows or shrinks a given memory block on the heap. If p is **nil**
-      ## then a new memory block is returned. In either way the block has at
-      ## least ``newSize`` bytes. If ``newSize == 0`` and p is not **nil**
-      ## ``reallocShared`` calls ``deallocShared(p)``. In other cases the
-      ## block has to be freed with ``deallocShared``.
+      ## Grows or shrinks a given memory block on the heap.
+      ##
+      ## If `p` is **nil** then a new memory block is returned.
+      ## In either way the block has at least ``newSize`` bytes.
+      ## If ``newSize == 0`` and `p` is not **nil** ``reallocShared`` calls
+      ## ``deallocShared(p)``.
+      ## In other cases the block has to be freed with
+      ## `deallocShared <#deallocShared,pointer>`_.
     proc resizeShared*[T](p: ptr T, newSize: Natural): ptr T {.inline, raises: [].} =
-      ## grows or shrinks a given memory block on the heap. If p is **nil**
-      ## then a new memory block is returned. In either way the block has at
-      ## least ``T.sizeof * newSize`` bytes. If ``newSize == 0`` and p is
-      ## not **nil** ``resizeShared`` calls ``freeShared(p)``. In other
-      ## cases the block has to be freed with ``freeShared``.
+      ## Grows or shrinks a given memory block on the heap.
+      ##
+      ## If `p` is **nil** then a new memory block is returned.
+      ## In either way the block has at least ``T.sizeof * newSize`` bytes.
+      ## If ``newSize == 0`` and `p` is not **nil** ``resizeShared`` calls
+      ## ``freeShared(p)``.
+      ## In other cases the block has to be freed with
+      ## `freeShared <#freeShared,ptr.T>`_.
       cast[ptr T](reallocShared(p, T.sizeof * newSize))
+
     proc deallocShared*(p: pointer) {.noconv, rtl, benign, raises: [].}
-      ## frees the memory allocated with ``allocShared``, ``allocShared0`` or
-      ## ``reallocShared``. This procedure is dangerous! If one forgets to
-      ## free the memory a leak occurs; if one tries to access freed
-      ## memory (or just freeing it twice!) a core dump may happen
+      ## Frees the memory allocated with ``allocShared``, ``allocShared0`` or
+      ## ``reallocShared``.
+      ##
+      ## **This procedure is dangerous!**
+      ## If one forgets to free the memory a leak occurs; if one tries to
+      ## access freed memory (or just freeing it twice!) a core dump may happen
       ## or other memory may be corrupted.
     proc freeShared*[T](p: ptr T) {.inline, benign, raises: [].} =
-      ## frees the memory allocated with ``createShared``, ``createSharedU`` or
-      ## ``resizeShared``. This procedure is dangerous! If one forgets to
-      ## free the memory a leak occurs; if one tries to access freed
-      ## memory (or just freeing it twice!) a core dump may happen
+      ## Frees the memory allocated with ``createShared``, ``createSharedU`` or
+      ## ``resizeShared``.
+      ##
+      ## **This procedure is dangerous!**
+      ## If one forgets to free the memory a leak occurs; if one tries to
+      ## access freed memory (or just freeing it twice!) a core dump may happen
       ## or other memory may be corrupted.
       deallocShared(p)
 
 proc swap*[T](a, b: var T) {.magic: "Swap", noSideEffect.}
-  ## swaps the values `a` and `b`. This is often more efficient than
-  ## ``tmp = a; a = b; b = tmp``. Particularly useful for sorting algorithms.
+  ## Swaps the values `a` and `b`.
+  ##
+  ## This is often more efficient than ``tmp = a; a = b; b = tmp``.
+  ## Particularly useful for sorting algorithms.
+  ##
+  ## .. code-block:: Nim
+  ##   var
+  ##     a = 5
+  ##     b = 9
+  ##
+  ##   swap(a, b)
+  ##
+  ##   assert a == 9
+  ##   assert b == 5
 
 when not defined(js) and not defined(booting) and defined(nimTrMacros):
   template swapRefsInArray*{swap(arr[a], arr[b])}(arr: openarray[ref], a, b: int) =
@@ -2030,21 +2444,13 @@ when not defined(js) and not defined(booting) and defined(nimTrMacros):
     # unnecessary slow down in this case.
     swap(cast[ptr pointer](addr arr[a])[], cast[ptr pointer](addr arr[b])[])
 
-template `>=%`*(x, y: untyped): untyped = y <=% x
-  ## treats `x` and `y` as unsigned and compares them.
-  ## Returns true iff ``unsigned(x) >= unsigned(y)``.
-
-template `>%`*(x, y: untyped): untyped = y <% x
-  ## treats `x` and `y` as unsigned and compares them.
-  ## Returns true iff ``unsigned(x) > unsigned(y)``.
-
 proc `$`*(x: int): string {.magic: "IntToStr", noSideEffect.}
   ## The stringify operator for an integer argument. Returns `x`
   ## converted to a decimal string. ``$`` is Nim's general way of
   ## spelling `toString`:idx:.
 
 proc `$`*(x: int64): string {.magic: "Int64ToStr", noSideEffect.}
-  ## The stringify operator for an integer argument. Returns `x`
+  ## The stringify operator for an `int64` argument. Returns `x`
   ## converted to a decimal string.
 
 when not defined(nimscript):
@@ -2064,6 +2470,9 @@ proc `$`*(x: bool): string {.magic: "BoolToStr", noSideEffect.}
 proc `$`*(x: char): string {.magic: "CharToStr", noSideEffect.}
   ## The stringify operator for a character argument. Returns `x`
   ## converted to a string.
+  ##
+  ## .. code-block:: Nim
+  ##   assert $'c' == "c"
 
 proc `$`*(x: cstring): string {.magic: "CStrToStr", noSideEffect.}
   ## The stringify operator for a CString argument. Returns `x`
@@ -2076,69 +2485,86 @@ proc `$`*(x: string): string {.magic: "StrToStr", noSideEffect.}
 
 proc `$`*[Enum: enum](x: Enum): string {.magic: "EnumToStr", noSideEffect.}
   ## The stringify operator for an enumeration argument. This works for
-  ## any enumeration type thanks to compiler magic. If
-  ## a ``$`` operator for a concrete enumeration is provided, this is
+  ## any enumeration type thanks to compiler magic.
+  ##
+  ## If a ``$`` operator for a concrete enumeration is provided, this is
   ## used instead. (In other words: *Overwriting* is possible.)
 
+proc `$`*(t: typedesc): string {.magic: "TypeTrait".} =
+  ## Returns the name of the given type.
+  ##
+  ## For more procedures dealing with ``typedesc``, see
+  ## `typetraits module <typetraits.html>`_.
+  runnableExamples:
+    doAssert $(type(42)) == "int"
+    doAssert $(type("Foo")) == "string"
+    static: doAssert $(type(@['A', 'B'])) == "seq[char]"
+
+
 # undocumented:
 proc getRefcount*[T](x: ref T): int {.importc: "getRefcount", noSideEffect,
   deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
+  ## Deprecated.
 proc getRefcount*(x: string): int {.importc: "getRefcount", noSideEffect,
   deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
+  ## Deprecated.
 proc getRefcount*[T](x: seq[T]): int {.importc: "getRefcount", noSideEffect,
   deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
-  ## retrieves the reference count of an heap-allocated object. The
+  ## Deprecated.
+  ##
+  ## Retrieves the reference count of an heap-allocated object. The
   ## value is implementation-dependent.
 
 
 const
   Inf* = 0x7FF0000000000000'f64
-    ## contains the IEEE floating point value of positive infinity.
+    ## Contains the IEEE floating point value of positive infinity.
   NegInf* = 0xFFF0000000000000'f64
-    ## contains the IEEE floating point value of negative infinity.
+    ## Contains the IEEE floating point value of negative infinity.
   NaN* = 0x7FF7FFFFFFFFFFFF'f64
-    ## contains an IEEE floating point value of *Not A Number*. Note
-    ## that you cannot compare a floating point value to this value
+    ## Contains an IEEE floating point value of *Not A Number*.
+    ##
+    ## Note that you cannot compare a floating point value to this value
     ## and expect a reasonable result - use the `classify` procedure
-    ## in the module ``math`` for checking for NaN.
+    ## in the `math module <math.html>`_ for checking for NaN.
   NimMajor* {.intdefine.}: int = 0
-    ## is the major number of Nim's version.
+    ## The major number of Nim's version.
 
   NimMinor* {.intdefine.}: int = 19
-    ## is the minor number of Nim's version.
+    ## The minor number of Nim's version.
 
   NimPatch* {.intdefine.}: int = 9
-    ## is the patch number of Nim's version.
+    ## The patch number of Nim's version.
 
   NimVersion*: string = $NimMajor & "." & $NimMinor & "." & $NimPatch
-    ## is the version of Nim as a string.
+    ## The version of Nim as a string.
 
 # GC interface:
 
 when not defined(nimscript) and hasAlloc:
   proc getOccupiedMem*(): int {.rtl.}
-    ## returns the number of bytes that are owned by the process and hold data.
+    ## Returns the number of bytes that are owned by the process and hold data.
 
   proc getFreeMem*(): int {.rtl.}
-    ## returns the number of bytes that are owned by the process, but do not
+    ## Returns the number of bytes that are owned by the process, but do not
     ## hold any meaningful data.
 
   proc getTotalMem*(): int {.rtl.}
-    ## returns the number of bytes that are owned by the process.
+    ## Returns the number of bytes that are owned by the process.
 
   when hasThreadSupport:
     proc getOccupiedSharedMem*(): int {.rtl.}
-      ## returns the number of bytes that are owned by the process
+      ## Returns the number of bytes that are owned by the process
       ## on the shared heap and hold data. This is only available when
       ## threads are enabled.
 
     proc getFreeSharedMem*(): int {.rtl.}
-      ## returns the number of bytes that are owned by the
+      ## Returns the number of bytes that are owned by the
       ## process on the shared heap, but do not hold any meaningful data.
       ## This is only available when threads are enabled.
 
     proc getTotalSharedMem*(): int {.rtl.}
-      ## returns the number of bytes on the shared heap that are owned by the
+      ## Returns the number of bytes on the shared heap that are owned by the
       ## process. This is only available when threads are enabled.
 
 proc `|`*(a, b: typedesc): typedesc = discard
@@ -2150,9 +2576,19 @@ else:
 
 iterator countdown*[T](a, b: T, step: Positive = 1): T {.inline.} =
   ## Counts from ordinal value `a` down to `b` (inclusive) with the given
-  ## step count. `T` may be any ordinal type, `step` may only
-  ## be positive. **Note**: This fails to count to ``low(int)`` if T = int for
+  ## step count.
+  ##
+  ## `T` may be any ordinal type, `step` may only be positive.
+  ##
+  ## **Note**: This fails to count to ``low(int)`` if T = int for
   ## efficiency reasons.
+  ##
+  ## .. code-block:: Nim
+  ##   for i in countdown(7, 3):
+  ##     echo i # => 7; 6; 5; 4; 3
+  ##
+  ##   for i in countdown(9, 2, 3):
+  ##     echo i # => 9; 6; 3
   when T is (uint|uint64):
     var res = a
     while res >= b:
@@ -2172,10 +2608,20 @@ iterator countdown*[T](a, b: T, step: Positive = 1): T {.inline.} =
 
 when defined(nimNewRoof):
   iterator countup*[T](a, b: T, step: Positive = 1): T {.inline.} =
-    ## Counts from ordinal value `a` up to `b` (inclusive) with the given
-    ## step count. `S`, `T` may be any ordinal type, `step` may only
-    ## be positive. **Note**: This fails to count to ``high(int)`` if T = int for
+    ## Counts from ordinal value `a` to `b` (inclusive) with the given
+    ## step count.
+    ##
+    ## `T` may be any ordinal type, `step` may only be positive.
+    ##
+    ## **Note**: This fails to count to ``high(int)`` if T = int for
     ## efficiency reasons.
+    ##
+    ## .. code-block:: Nim
+    ##   for i in countup(3, 7):
+    ##     echo i # => 3; 4; 5; 6; 7
+    ##
+    ##   for i in countup(2, 9, 3):
+    ##     echo i # => 2; 5; 8
     when T is IntLikeForCount:
       var res = int(a)
       while res <= int(b):
@@ -2189,6 +2635,13 @@ when defined(nimNewRoof):
 
   iterator `..`*[T](a, b: T): T {.inline.} =
     ## An alias for `countup(a, b, 1)`.
+    ##
+    ## See also:
+    ## * [..<](#..<.i,T,T)
+    ##
+    ## .. code-block:: Nim
+    ##   for i in 3 .. 7:
+    ##     echo i # => 3; 4; 5; 6; 7
     when T is IntLikeForCount:
       var res = int(a)
       while res <= int(b):
@@ -2204,6 +2657,9 @@ when defined(nimNewRoof):
     iterator `..`*(a, b: t): t {.inline.} =
       ## A type specialized version of ``..`` for convenience so that
       ## mixing integer types works better.
+      ##
+      ## See also:
+      ## * [..<](#..<.i,T,T)
       var res = a
       while res <= b:
         yield res
@@ -2223,9 +2679,19 @@ when defined(nimNewRoof):
 else:
   iterator countup*[S, T](a: S, b: T, step = 1): T {.inline.} =
     ## Counts from ordinal value `a` up to `b` (inclusive) with the given
-    ## step count. `S`, `T` may be any ordinal type, `step` may only
-    ## be positive. **Note**: This fails to count to ``high(int)`` if T = int for
+    ## step count.
+    ##
+    ## `S`, `T` may be any ordinal type, `step` may only be positive.
+    ##
+    ## **Note**: This fails to count to ``high(int)`` if T = int for
     ## efficiency reasons.
+    ##
+    ## .. code-block:: Nim
+    ##   for i in countup(3, 7):
+    ##     echo i # => 3; 4; 5; 6; 7
+    ##
+    ##   for i in countup(2, 9, 3):
+    ##     echo i # => 2; 5; 8
     when T is IntLikeForCount:
       var res = int(a)
       while res <= int(b):
@@ -2238,7 +2704,14 @@ else:
         inc(res, step)
 
   iterator `..`*[S, T](a: S, b: T): T {.inline.} =
-    ## An alias for `countup`.
+    ## An alias for `countup(a, b, 1)`.
+    ##
+    ## See also:
+    ## * [..<](#..<.i,T,T)
+    ##
+    ## .. code-block:: Nim
+    ##   for i in 3 .. 7:
+    ##     echo i # => 3; 4; 5; 6; 7
     when T is IntLikeForCount:
       var res = int(a)
       while res <= int(b):
@@ -2260,9 +2733,11 @@ else:
 iterator `||`*[S, T](a: S, b: T, annotation: static string = "parallel for"): T {.
   inline, magic: "OmpParFor", sideEffect.} =
   ## OpenMP parallel loop iterator. Same as `..` but the loop may run in parallel.
+  ##
   ## `annotation` is an additional annotation for the code generator to use.
   ## The default annotation is `parallel for`.
-  ## Please refer to the `OpenMP Syntax Reference<https://www.openmp.org/wp-content/uploads/OpenMP-4.5-1115-CPP-web.pdf>`_
+  ## Please refer to the `OpenMP Syntax Reference
+  ## <https://www.openmp.org/wp-content/uploads/OpenMP-4.5-1115-CPP-web.pdf>`_
   ## for further information.
   ##
   ## Note that the compiler maps that to
@@ -2327,7 +2802,7 @@ proc high*(T: typedesc[SomeFloat]): T = Inf
 proc low*(T: typedesc[SomeFloat]): T = NegInf
 
 proc clamp*[T](x, a, b: T): T =
-  ## limits the value ``x`` within the interval [a, b]
+  ## Limits the value ``x`` within the interval [a, b].
   ##
   ## .. code-block:: Nim
   ##   assert((1.4).clamp(0.0, 1.0) == 1.0)
@@ -2337,7 +2812,7 @@ proc clamp*[T](x, a, b: T): T =
   return x
 
 proc len*[U: Ordinal; V: Ordinal](x: HSlice[U, V]): int {.noSideEffect, inline.} =
-  ## length of ordinal slice, when x.b < x.a returns zero length
+  ## Length of ordinal slice. When x.b < x.a returns zero length.
   ##
   ## .. code-block:: Nim
   ##   assert((0..5).len == 6)
@@ -2380,16 +2855,21 @@ proc `==`*[T](x, y: openarray[T]): bool =
   result = true
 
 proc `@`*[T](a: openArray[T]): seq[T] =
-  ## turns an openarray into a sequence. This is not as efficient as turning
-  ## a fixed length array into a sequence as it always copies every element
-  ## of `a`.
+  ## Turns an *openarray* into a sequence.
+  ##
+  ## This is not as efficient as turning a fixed length array into a sequence
+  ## as it always copies every element of `a`.
   newSeq(result, a.len)
   for i in 0..a.len-1: result[i] = a[i]
 
 proc `&`*[T](x, y: seq[T]): seq[T] {.noSideEffect.} =
   ## Concatenates two sequences.
+  ##
   ## Requires copying of the sequences.
   ##
+  ## See also:
+  ## * `add(var seq[T], openArray[T]) <#add,seq[T][T],openArray[T]>`_
+  ##
   ## .. code-block:: Nim
   ##   assert(@[1, 2, 3, 4] & @[5, 6] == @[1, 2, 3, 4, 5, 6])
   newSeq(result, x.len + y.len)
@@ -2400,7 +2880,11 @@ proc `&`*[T](x, y: seq[T]): seq[T] {.noSideEffect.} =
 
 proc `&`*[T](x: seq[T], y: T): seq[T] {.noSideEffect.} =
   ## Appends element y to the end of the sequence.
-  ## Requires copying of the sequence
+  ##
+  ## Requires copying of the sequence.
+  ##
+  ## See also:
+  ## * `add(var seq[T], T) <#add,seq[T][T],T>`_
   ##
   ## .. code-block:: Nim
   ##   assert(@[1, 2, 3] & 4 == @[1, 2, 3, 4])
@@ -2411,7 +2895,8 @@ proc `&`*[T](x: seq[T], y: T): seq[T] {.noSideEffect.} =
 
 proc `&`*[T](x: T, y: seq[T]): seq[T] {.noSideEffect.} =
   ## Prepends the element x to the beginning of the sequence.
-  ## Requires copying of the sequence
+  ##
+  ## Requires copying of the sequence.
   ##
   ## .. code-block:: Nim
   ##   assert(1 & @[2, 3, 4] == @[1, 2, 3, 4])
@@ -2519,21 +3004,26 @@ proc contains*[T](a: openArray[T], item: T): bool {.inline.}=
   return find(a, item) >= 0
 
 proc pop*[T](s: var seq[T]): T {.inline, noSideEffect.} =
-  ## returns the last item of `s` and decreases ``s.len`` by one. This treats
+  ## Returns the last item of `s` and decreases ``s.len`` by one. This treats
   ## `s` as a stack and implements the common *pop* operation.
+  runnableExamples:
+    var a = @[1, 3, 5, 7]
+    let b = pop(a)
+    assert b == 7
+
   var L = s.len-1
   result = s[L]
   setLen(s, L)
 
 proc `==`*[T: tuple|object](x, y: T): bool =
-  ## generic ``==`` operator for tuples that is lifted from the components
+  ## Generic ``==`` operator for tuples that is lifted from the components.
   ## of `x` and `y`.
   for a, b in fields(x, y):
     if a != b: return false
   return true
 
 proc `<=`*[T: tuple](x, y: T): bool =
-  ## generic lexicographic ``<=`` operator for tuples that is lifted from the
+  ## Generic lexicographic ``<=`` operator for tuples that is lifted from the
   ## components of `x` and `y`. This implementation uses `cmp`.
   for a, b in fields(x, y):
     var c = cmp(a, b)
@@ -2542,7 +3032,7 @@ proc `<=`*[T: tuple](x, y: T): bool =
   return true
 
 proc `<`*[T: tuple](x, y: T): bool =
-  ## generic lexicographic ``<`` operator for tuples that is lifted from the
+  ## Generic lexicographic ``<`` operator for tuples that is lifted from the
   ## components of `x` and `y`. This implementation uses `cmp`.
   for a, b in fields(x, y):
     var c = cmp(a, b)
@@ -2553,6 +3043,7 @@ proc `<`*[T: tuple](x, y: T): bool =
 proc compiles*(x: untyped): bool {.magic: "Compiles", noSideEffect, compileTime.} =
   ## Special compile-time procedure that checks whether `x` can be compiled
   ## without any semantic error.
+  ##
   ## This can be used to check whether a type supports some operation:
   ##
   ## .. code-block:: Nim
@@ -2563,10 +3054,10 @@ proc compiles*(x: untyped): bool {.magic: "Compiles", noSideEffect, compileTime.
 include "system/helpers" # for `lineInfoToString`, `isNamedTuple`
 
 proc `$`*[T: tuple|object](x: T): string =
-  ## generic ``$`` operator for tuples that is lifted from the components
+  ## Generic ``$`` operator for tuples that is lifted from the components
   ## of `x`. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   $(23, 45) == "(23, 45)"
   ##   $(a: 23, b: 45) == "(a: 23, b: 45)"
   ##   $() == "()"
@@ -2618,26 +3109,26 @@ proc collectionToString[T](x: T, prefix, separator, suffix: string): string =
   result.add(suffix)
 
 proc `$`*[T](x: set[T]): string =
-  ## generic ``$`` operator for sets that is lifted from the components
+  ## Generic ``$`` operator for sets that is lifted from the components
   ## of `x`. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   ${23, 45} == "{23, 45}"
   collectionToString(x, "{", ", ", "}")
 
 proc `$`*[T](x: seq[T]): string =
-  ## generic ``$`` operator for seqs that is lifted from the components
+  ## Generic ``$`` operator for seqs that is lifted from the components
   ## of `x`. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   $(@[23, 45]) == "@[23, 45]"
   collectionToString(x, "@[", ", ", "]")
 
 proc `$`*[T, U](x: HSlice[T, U]): string =
-  ## generic ``$`` operator for slices that is lifted from the components
+  ## Generic ``$`` operator for slices that is lifted from the components
   ## of `x`. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##  $(1 .. 5) == "1 .. 5"
   result = $x.a
   result.add(" .. ")
@@ -2647,7 +3138,7 @@ proc `$`*[T, U](x: HSlice[T, U]): string =
 
 when not defined(nimscript) and hasAlloc:
   type
-    GC_Strategy* = enum ## the strategy the GC should use for the application
+    GC_Strategy* = enum  ## The strategy the GC should use for the application.
       gcThroughput,      ## optimize for throughput
       gcResponsiveness,  ## optimize for responsiveness (default)
       gcOptimizeTime,    ## optimize for speed
@@ -2655,40 +3146,44 @@ when not defined(nimscript) and hasAlloc:
 
   when not defined(JS):
     proc GC_disable*() {.rtl, inl, benign.}
-      ## disables the GC. If called n-times, n calls to `GC_enable` are needed to
-      ## reactivate the GC. Note that in most circumstances one should only disable
-      ## the mark and sweep phase with `GC_disableMarkAndSweep`.
+      ## Disables the GC. If called `n` times, `n` calls to `GC_enable`
+      ## are needed to reactivate the GC.
+      ##
+      ## Note that in most circumstances one should only disable
+      ## the mark and sweep phase with
+      ## `GC_disableMarkAndSweep <#GC_disableMarkAndSweep>`_.
 
     proc GC_enable*() {.rtl, inl, benign.}
-      ## enables the GC again.
+      ## Enables the GC again.
 
     proc GC_fullCollect*() {.rtl, benign.}
-      ## forces a full garbage collection pass.
+      ## Forces a full garbage collection pass.
       ## Ordinary code does not need to call this (and should not).
 
     proc GC_enableMarkAndSweep*() {.rtl, benign.}
     proc GC_disableMarkAndSweep*() {.rtl, benign.}
-      ## the current implementation uses a reference counting garbage collector
+      ## The current implementation uses a reference counting garbage collector
       ## with a seldomly run mark and sweep phase to free cycles. The mark and
       ## sweep phase may take a long time and is not needed if the application
       ## does not create cycles. Thus the mark and sweep phase can be deactivated
       ## and activated separately from the rest of the GC.
 
     proc GC_getStatistics*(): string {.rtl, benign.}
-      ## returns an informative string about the GC's activity. This may be useful
+      ## Returns an informative string about the GC's activity. This may be useful
       ## for tweaking.
 
     proc GC_ref*[T](x: ref T) {.magic: "GCref", benign.}
     proc GC_ref*[T](x: seq[T]) {.magic: "GCref", benign.}
     proc GC_ref*(x: string) {.magic: "GCref", benign.}
-      ## marks the object `x` as referenced, so that it will not be freed until
-      ## it is unmarked via `GC_unref`. If called n-times for the same object `x`,
+      ## Marks the object `x` as referenced, so that it will not be freed until
+      ## it is unmarked via `GC_unref`.
+      ## If called n-times for the same object `x`,
       ## n calls to `GC_unref` are needed to unmark `x`.
 
     proc GC_unref*[T](x: ref T) {.magic: "GCunref", benign.}
     proc GC_unref*[T](x: seq[T]) {.magic: "GCunref", benign.}
     proc GC_unref*(x: string) {.magic: "GCunref", benign.}
-      ## see the documentation of `GC_ref`.
+      ## See the documentation of `GC_ref <#GC_ref,string>`_.
 
     when not defined(JS) and not defined(nimscript) and hasAlloc:
       proc nimGC_setStackBottom*(theStackBottom: pointer) {.compilerRtl, noinline, benign.}
@@ -2736,12 +3231,13 @@ when not defined(nimscript) and hasAlloc:
       {.warning: "GC_getStatistics is a no-op in JavaScript".}
       ""
 
-template accumulateResult*(iter: untyped) {.deprecated:
-    "use `sequtils.toSeq` instead (more hygienic, sometimes more efficient)".} =
-  ## helps to convert an iterator to a proc.
-  ## See also `sequtils.toSeq` which is more hygienic and efficient.
+template accumulateResult*(iter: untyped) {.deprecated: "use `sequtils.toSeq` instead (more hygienic, sometimes more efficient)".} =
+  ## **Deprecated since v0.19.2:** use `sequtils.toSeq
+  ## <sequtils.html#toSeq.t,untyped>`_ instead.
+  ##
+  ## Helps to convert an iterator to a proc.
+  ## `sequtils.toSeq <sequtils.html#toSeq.t,untyped>`_ is more hygienic and efficient.
   ##
-  ## **Deprecated since v0.19.2:** use toSeq instead
   result = @[]
   for x in iter: add(result, x)
 
@@ -2776,28 +3272,34 @@ else:
 
 var
   globalRaiseHook*: proc (e: ref Exception): bool {.nimcall, benign.}
-    ## with this hook you can influence exception handling on a global level.
-    ## If not nil, every 'raise' statement ends up calling this hook. Ordinary
-    ## application code should never set this hook! You better know what you
-    ## do when setting this. If ``globalRaiseHook`` returns false, the
-    ## exception is caught and does not propagate further through the call
-    ## stack.
+    ## With this hook you can influence exception handling on a global level.
+    ## If not nil, every 'raise' statement ends up calling this hook.
+    ##
+    ## **Warning**: Ordinary application code should never set this hook!
+    ## You better know what you do when setting this.
+    ##
+    ## If ``globalRaiseHook`` returns false, the exception is caught and does
+    ## not propagate further through the call stack.
 
   localRaiseHook* {.threadvar.}: proc (e: ref Exception): bool {.nimcall, benign.}
-    ## with this hook you can influence exception handling on a
+    ## With this hook you can influence exception handling on a
     ## thread local level.
-    ## If not nil, every 'raise' statement ends up calling this hook. Ordinary
-    ## application code should never set this hook! You better know what you
-    ## do when setting this. If ``localRaiseHook`` returns false, the exception
+    ## If not nil, every 'raise' statement ends up calling this hook.
+    ##
+    ## **Warning**: Ordinary application code should never set this hook!
+    ## You better know what you do when setting this.
+    ##
+    ## If ``localRaiseHook`` returns false, the exception
     ## is caught and does not propagate further through the call stack.
 
   outOfMemHook*: proc () {.nimcall, tags: [], benign, raises: [].}
-    ## set this variable to provide a procedure that should be called
+    ## Set this variable to provide a procedure that should be called
     ## in case of an `out of memory`:idx: event. The standard handler
-    ## writes an error message and terminates the program. `outOfMemHook` can
-    ## be used to raise an exception in case of OOM like so:
+    ## writes an error message and terminates the program.
     ##
-    ## .. code-block:: nim
+    ## `outOfMemHook` can be used to raise an exception in case of OOM like so:
+    ##
+    ## .. code-block:: Nim
     ##
     ##   var gOutOfMem: ref EOutOfMemory
     ##   new(gOutOfMem) # need to be allocated *before* OOM really happened!
@@ -2812,15 +3314,15 @@ var
     ## continues and the program is terminated.
 
 type
-  PFrame* = ptr TFrame  ## represents a runtime frame of the call stack;
+  PFrame* = ptr TFrame  ## Represents a runtime frame of the call stack;
                         ## part of the debugger API.
-  TFrame* {.importc, nodecl, final.} = object ## the frame itself
-    prev*: PFrame       ## previous frame; used for chaining the call stack
-    procname*: cstring  ## name of the proc that is currently executing
-    line*: int          ## line number of the proc that is currently executing
-    filename*: cstring  ## filename of the proc that is currently executing
-    len*: int16         ## length of the inspectable slots
-    calldepth*: int16   ## used for max call depth checking
+  TFrame* {.importc, nodecl, final.} = object ## The frame itself.
+    prev*: PFrame       ## Previous frame; used for chaining the call stack.
+    procname*: cstring  ## Name of the proc that is currently executing.
+    line*: int          ## Line number of the proc that is currently executing.
+    filename*: cstring  ## Filename of the proc that is currently executing.
+    len*: int16         ## Length of the inspectable slots.
+    calldepth*: int16   ## Used for max call depth checking.
 
 when defined(JS):
   proc add*(x: var string, y: cstring) {.asmNoStackFrame.} =
@@ -2873,7 +3375,7 @@ else:
 
 template newException*(exceptn: typedesc, message: string;
                        parentException: ref Exception = nil): untyped =
-  ## creates an exception object of type ``exceptn`` and sets its ``msg`` field
+  ## Creates an exception object of type ``exceptn`` and sets its ``msg`` field
   ## to `message`. Returns the new exception object.
   when declared(owned):
     var e: owned(ref exceptn)
@@ -2896,8 +3398,10 @@ when not declared(sysFatal):
   include "system/fatal"
 
 proc getTypeInfo*[T](x: T): pointer {.magic: "GetTypeInfo", benign.}
-  ## get type information for `x`. Ordinary code should not use this, but
-  ## the `typeinfo` module instead.
+  ## Get type information for `x`.
+  ##
+  ## Ordinary code should not use this, but the `typeinfo module
+  ## <typeinfo.html>`_ instead.
 
 {.push stackTrace: off.}
 proc abs*(x: int): int {.magic: "AbsI", noSideEffect.} =
@@ -2910,15 +3414,17 @@ proc abs*(x: int32): int32 {.magic: "AbsI", noSideEffect.} =
   if x < 0: -x else: x
 when defined(nimnomagic64):
   proc abs*(x: int64): int64 {.magic: "AbsI", noSideEffect.} =
-    ## returns the absolute value of `x`. If `x` is ``low(x)`` (that
-    ## is -MININT for its type), an overflow exception is thrown (if overflow
-    ## checking is turned on).
+    ## Returns the absolute value of `x`.
+    ##
+    ## If `x` is ``low(x)`` (that is -MININT for its type),
+    ## an overflow exception is thrown (if overflow checking is turned on).
     result = if x < 0: -x else: x
 else:
   proc abs*(x: int64): int64 {.magic: "AbsI64", noSideEffect.} =
-    ## returns the absolute value of `x`. If `x` is ``low(x)`` (that
-    ## is -MININT for its type), an overflow exception is thrown (if overflow
-    ## checking is turned on).
+    ## Returns the absolute value of `x`.
+    ##
+    ## If `x` is ``low(x)`` (that is -MININT for its type),
+    ## an overflow exception is thrown (if overflow checking is turned on).
     if x < 0: -x else: x
 {.pop.}
 
@@ -2934,7 +3440,7 @@ template likely*(val: bool): bool =
   ## platforms this can help the processor predict better which branch is
   ## going to be run. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   for value in inputValues:
   ##     if likely(value <= 100):
   ##       process(value)
@@ -2958,7 +3464,7 @@ template unlikely*(val: bool): bool =
   ## platforms this can help the processor predict better which branch is
   ## going to be run. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   for value in inputValues:
   ##     if unlikely(value > 100):
   ##       echo "Value too big!"
@@ -2976,7 +3482,7 @@ template unlikely*(val: bool): bool =
       unlikelyProc(val)
 
 type
-  FileSeekPos* = enum ## Position relative to which seek should happen
+  FileSeekPos* = enum ## Position relative to which seek should happen.
                       # The values are ordered so that they match with stdio
                       # SEEK_SET, SEEK_CUR and SEEK_END respectively.
     fspSet            ## Seek to absolute value
@@ -3059,13 +3565,13 @@ when not defined(JS): #and not defined(nimscript):
 
   when declared(newSeq):
     proc cstringArrayToSeq*(a: cstringArray, len: Natural): seq[string] =
-      ## converts a ``cstringArray`` to a ``seq[string]``. `a` is supposed to be
+      ## Converts a ``cstringArray`` to a ``seq[string]``. `a` is supposed to be
       ## of length ``len``.
       newSeq(result, len)
       for i in 0..len-1: result[i] = $a[i]
 
     proc cstringArrayToSeq*(a: cstringArray): seq[string] =
-      ## converts a ``cstringArray`` to a ``seq[string]``. `a` is supposed to be
+      ## Converts a ``cstringArray`` to a ``seq[string]``. `a` is supposed to be
       ## terminated by ``nil``.
       var L = 0
       while a[L] != nil: inc(L)
@@ -3075,7 +3581,7 @@ when not defined(JS): #and not defined(nimscript):
 
   when declared(alloc0) and declared(dealloc):
     proc allocCStringArray*(a: openArray[string]): cstringArray =
-      ## creates a NULL terminated cstringArray from `a`. The result has to
+      ## Creates a NULL terminated cstringArray from `a`. The result has to
       ## be freed with `deallocCStringArray` after it's not needed anymore.
       result = cast[cstringArray](alloc0((a.len+1) * sizeof(cstring)))
 
@@ -3085,7 +3591,7 @@ when not defined(JS): #and not defined(nimscript):
         copyMem(result[i], addr(x[i][0]), x[i].len)
 
     proc deallocCStringArray*(a: cstringArray) =
-      ## frees a NULL terminated cstringArray.
+      ## Frees a NULL terminated cstringArray.
       var i = 0
       while a[i] != nil:
         dealloc(a[i])
@@ -3095,11 +3601,11 @@ when not defined(JS): #and not defined(nimscript):
   when not defined(nimscript):
     proc atomicInc*(memLoc: var int, x: int = 1): int {.inline,
       discardable, benign.}
-      ## atomic increment of `memLoc`. Returns the value after the operation.
+      ## Atomic increment of `memLoc`. Returns the value after the operation.
 
     proc atomicDec*(memLoc: var int, x: int = 1): int {.inline,
       discardable, benign.}
-      ## atomic decrement of `memLoc`. Returns the value after the operation.
+      ## Atomic decrement of `memLoc`. Returns the value after the operation.
 
     include "system/atomics"
 
@@ -3125,23 +3631,23 @@ when not defined(JS): #and not defined(nimscript):
 
   when not defined(nimscript):
     proc setControlCHook*(hook: proc () {.noconv.})
-      ## allows you to override the behaviour of your application when CTRL+C
+      ## Allows you to override the behaviour of your application when CTRL+C
       ## is pressed. Only one such hook is supported.
 
     when not defined(noSignalHandler) and not defined(useNimRtl):
       proc unsetControlCHook*()
-        ## reverts a call to setControlCHook
+        ## Reverts a call to setControlCHook.
 
     proc writeStackTrace*() {.tags: [], gcsafe.}
-      ## writes the current stack trace to ``stderr``. This is only works
+      ## Writes the current stack trace to ``stderr``. This is only works
       ## for debug builds. Since it's usually used for debugging, this
       ## is proclaimed to have no IO effect!
     when hostOS != "standalone":
       proc getStackTrace*(): string {.gcsafe.}
-        ## gets the current stack trace. This only works for debug builds.
+        ## Gets the current stack trace. This only works for debug builds.
 
       proc getStackTrace*(e: ref Exception): string {.gcsafe.}
-        ## gets the stack trace associated with `e`, which is the stack that
+        ## Gets the stack trace associated with `e`, which is the stack that
         ## lead to the ``raise`` statement. This only works for debug builds.
 
     {.push stack_trace: off, profiler:off.}
@@ -3211,30 +3717,30 @@ when not defined(JS): #and not defined(nimscript):
 
   when hostOS != "standalone" and not defined(nimscript):
     proc getCurrentException*(): ref Exception {.compilerRtl, inl, benign.} =
-      ## retrieves the current exception; if there is none, nil is returned.
+      ## Retrieves the current exception; if there is none, `nil` is returned.
       result = currException
 
     proc getCurrentExceptionMsg*(): string {.inline, benign.} =
-      ## retrieves the error message that was attached to the current
-      ## exception; if there is none, "" is returned.
+      ## Retrieves the error message that was attached to the current
+      ## exception; if there is none, `""` is returned.
       var e = getCurrentException()
       return if e == nil: "" else: e.msg
 
     proc onRaise*(action: proc(e: ref Exception): bool{.closure.}) {.deprecated.} =
-      ## can be used in a ``try`` statement to setup a Lisp-like
+      ## **Deprecated since version 0.18.1**: No good usages of this
+      ## feature are known.
+      ##
+      ## Can be used in a ``try`` statement to setup a Lisp-like
       ## `condition system`:idx:\: This prevents the 'raise' statement to
       ## raise an exception but instead calls ``action``.
       ## If ``action`` returns false, the exception has been handled and
       ## does not propagate further through the call stack.
-      ##
-      ## *Deprecated since version 0.18.1*: No good usages of this
-      ## feature are known.
       if not isNil(excHandler):
         excHandler.hasRaiseAction = true
         excHandler.raiseAction = action
 
     proc setCurrentException*(exc: ref Exception) {.inline, benign.} =
-      ## sets the current exception.
+      ## Sets the current exception.
       ##
       ## **Warning**: Only use this if you know what you are doing.
       currException = exc
@@ -3249,14 +3755,14 @@ when not defined(JS): #and not defined(nimscript):
 
   when not defined(nimscript):
     proc rawProc*[T: proc](x: T): pointer {.noSideEffect, inline.} =
-      ## retrieves the raw proc pointer of the closure `x`. This is
+      ## Retrieves the raw proc pointer of the closure `x`. This is
       ## useful for interfacing closures with C.
       {.emit: """
       `result` = `x`.ClP_0;
       """.}
 
     proc rawEnv*[T: proc](x: T): pointer {.noSideEffect, inline.} =
-      ## retrieves the raw environment pointer of the closure `x`. This is
+      ## Retrieves the raw environment pointer of the closure `x`. This is
       ## useful for interfacing closures with C.
       {.emit: """
       `result` = `x`.ClE_0;
@@ -3295,19 +3801,19 @@ elif defined(JS):
 
 when not defined(nimNoArrayToString):
   proc `$`*[T, IDX](x: array[IDX, T]): string =
-    ## generic ``$`` operator for arrays that is lifted from the components
+    ## Generic ``$`` operator for arrays that is lifted from the components.
     collectionToString(x, "[", ", ", "]")
 
 proc `$`*[T](x: openarray[T]): string =
-  ## generic ``$`` operator for openarrays that is lifted from the components
+  ## Generic ``$`` operator for openarrays that is lifted from the components
   ## of `x`. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   $(@[23, 45].toOpenArray(0, 1)) == "[23, 45]"
   collectionToString(x, "[", ", ", "]")
 
 proc quit*(errormsg: string, errorcode = QuitFailure) {.noReturn.} =
-  ## a shorthand for ``echo(errormsg); quit(errorcode)``.
+  ## A shorthand for ``echo(errormsg); quit(errorcode)``.
   when defined(nimscript) or defined(js) or (hostOS == "standalone"):
     echo errormsg
   else:
@@ -3319,24 +3825,40 @@ proc quit*(errormsg: string, errorcode = QuitFailure) {.noReturn.} =
 {.pop.} # hints
 
 proc `/`*(x, y: int): float {.inline, noSideEffect.} =
-  ## integer division that results in a float.
+  ## Integer division that results in a float.
+  ##
+  ## .. code-block:: Nim
+  ##   echo 7 / 5 # => 1.4
   result = toFloat(x) / toFloat(y)
 
 type
-  BackwardsIndex* = distinct int ## type that is constructed by ``^`` for
+  BackwardsIndex* = distinct int ## Type that is constructed by ``^`` for
                                  ## reversed array accesses.
+                                 ## (See `^ template <#^.t,int>`_)
 
 template `^`*(x: int): BackwardsIndex = BackwardsIndex(x)
-  ## builtin `roof`:idx: operator that can be used for convenient array access.
+  ## Builtin `roof`:idx: operator that can be used for convenient array access.
   ## ``a[^x]`` is a shortcut for ``a[a.len-x]``.
+  ##
+  ## .. code-block:: Nim
+  ##   let
+  ##     a = [1, 3, 5, 7, 9]
+  ##     b = "abcdefgh"
+  ##
+  ##   echo a[^1] # => 9
+  ##   echo b[^2] # => g
 
 template `..^`*(a, b: untyped): untyped =
-  ## a shortcut for '.. ^' to avoid the common gotcha that a space between
+  ## A shortcut for `.. ^` to avoid the common gotcha that a space between
   ## '..' and '^' is required.
   a .. ^b
 
 template `..<`*(a, b: untyped): untyped =
-  ## a shortcut for 'a .. (when b is BackwardsIndex: succ(b) else: pred(b))'.
+  ## A shortcut for `a .. pred(b)`.
+  ##
+  ## .. code-block:: Nim
+  ##   for i in 5 ..< 9:
+  ##     echo i # => 5; 6; 7; 8
   a .. (when b is BackwardsIndex: succ(b) else: pred(b))
 
 template spliceImpl(s, a, L, b: untyped): untyped =
@@ -3362,10 +3884,10 @@ template `[]=`*(s: string; i: int; val: char) = arrPut(s, i, val)
 
 when hasAlloc or defined(nimscript):
   proc `[]`*[T, U](s: string, x: HSlice[T, U]): string {.inline.} =
-    ## slice operation for strings.
-    ## returns the inclusive range [s[x.a], s[x.b]]:
+    ## Slice operation for strings.
+    ## Returns the inclusive range `[s[x.a], s[x.b]]`:
     ##
-    ## .. code-block:: nim
+    ## .. code-block:: Nim
     ##    var s = "abcdef"
     ##    assert s[1..3] == "bcd"
     let a = s ^^ x.a
@@ -3374,14 +3896,16 @@ when hasAlloc or defined(nimscript):
     for i in 0 ..< L: result[i] = s[i + a]
 
   proc `[]=`*[T, U](s: var string, x: HSlice[T, U], b: string) =
-    ## slice assignment for strings. If
-    ## ``b.len`` is not exactly the number of elements that are referred to
+    ## Slice assignment for strings.
+    ##
+    ## If ``b.len`` is not exactly the number of elements that are referred to
     ## by `x`, a `splice`:idx: is performed:
     ##
-    ## .. code-block:: nim
-    ##   var s = "abcdef"
-    ##   s[1 .. ^2] = "xyz"
-    ##   assert s == "axyzf"
+    runnableExamples:
+      var s = "abcdefgh"
+      s[1 .. ^2] = "xyz"
+      assert s == "axyzh"
+
     var a = s ^^ x.a
     var L = (s ^^ x.b) - a + 1
     if L == b.len:
@@ -3390,42 +3914,48 @@ when hasAlloc or defined(nimscript):
       spliceImpl(s, a, L, b)
 
 proc `[]`*[Idx, T, U, V](a: array[Idx, T], x: HSlice[U, V]): seq[T] =
-  ## slice operation for arrays.
-  ## returns the inclusive range [a[x.a], a[x.b]]:
+  ## Slice operation for arrays.
+  ## Returns the inclusive range `[a[x.a], a[x.b]]`:
   ##
-  ## .. code-block:: nim
-  ##    var a = [1,2,3,4]
-  ##    assert a[0..2] == @[1,2,3]
+  ## .. code-block:: Nim
+  ##    var a = [1, 2, 3, 4]
+  ##    assert a[0..2] == @[1, 2, 3]
   let xa = a ^^ x.a
   let L = (a ^^ x.b) - xa + 1
   result = newSeq[T](L)
   for i in 0..<L: result[i] = a[Idx(i + xa)]
 
 proc `[]=`*[Idx, T, U, V](a: var array[Idx, T], x: HSlice[U, V], b: openArray[T]) =
-  ## slice assignment for arrays.
+  ## Slice assignment for arrays.
   let xa = a ^^ x.a
   let L = (a ^^ x.b) - xa + 1
   if L == b.len:
     for i in 0..<L: a[Idx(i + xa)] = b[i]
   else:
-    sysFatal(RangeError, "different lengths for slice assignment")
+    sysFatal(RangeError, "diferent lengths for slice assignment")
 
 proc `[]`*[T, U, V](s: openArray[T], x: HSlice[U, V]): seq[T] =
-  ## slice operation for sequences.
-  ## returns the inclusive range [s[x.a], s[x.b]]:
+  ## Slice operation for sequences.
+  ## Returns the inclusive range `[s[x.a], s[x.b]]`:
   ##
-  ## .. code-block:: nim
-  ##    var s = @[1,2,3,4]
-  ##    assert s[0..2] == @[1,2,3]
+  ## .. code-block:: Nim
+  ##    var s = @[1, 2, 3, 4]
+  ##    assert s[0..2] == @[1, 2, 3]
   let a = s ^^ x.a
   let L = (s ^^ x.b) - a + 1
   newSeq(result, L)
   for i in 0 ..< L: result[i] = s[i + a]
 
 proc `[]=`*[T, U, V](s: var seq[T], x: HSlice[U, V], b: openArray[T]) =
-  ## slice assignment for sequences. If
-  ## ``b.len`` is not exactly the number of elements that are referred to
+  ## Slice assignment for sequences.
+  ##
+  ## If ``b.len`` is not exactly the number of elements that are referred to
   ## by `x`, a `splice`:idx: is performed.
+  runnableExamples:
+    var s = @"abcdefgh"
+    s[1 .. ^2] = @"xyz"
+    assert s == @"axyzh"
+
   let a = s ^^ x.a
   let L = (s ^^ x.b) - a + 1
   if L == b.len:
@@ -3453,34 +3983,36 @@ proc `[]=`*(s: var string; i: BackwardsIndex; x: char) {.inline.} =
   s[s.len - int(i)] = x
 
 proc slurp*(filename: string): string {.magic: "Slurp".}
-  ## This is an alias for `staticRead <#staticRead>`_.
+  ## This is an alias for `staticRead <#staticRead,string>`_.
 
 proc staticRead*(filename: string): string {.magic: "Slurp".}
-  ## Compile-time `readFile <#readFile>`_ proc for easy `resource`:idx:
-  ## embedding:
+  ## Compile-time `readFile <io.html#readFile,string>`_ proc for easy
+  ## `resource`:idx: embedding:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##     const myResource = staticRead"mydatafile.bin"
   ##
-  ## `slurp <#slurp>`_ is an alias for ``staticRead``.
+  ## `slurp <#slurp,string>`_ is an alias for ``staticRead``.
 
 proc gorge*(command: string, input = "", cache = ""): string {.
   magic: "StaticExec".} = discard
-  ## This is an alias for `staticExec <#staticExec>`_.
+  ## This is an alias for `staticExec <#staticExec,string,string,string>`_.
 
 proc staticExec*(command: string, input = "", cache = ""): string {.
   magic: "StaticExec".} = discard
   ## Executes an external process at compile-time.
-  ## if `input` is not an empty string, it will be passed as a standard input
+  ##
+  ## If `input` is not an empty string, it will be passed as a standard input
   ## to the executed program.
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##     const buildInfo = "Revision " & staticExec("git rev-parse HEAD") &
   ##                       "\nCompiled on " & staticExec("uname -v")
   ##
-  ## `gorge <#gorge>`_ is an alias for ``staticExec``. Note that you can use
-  ## this proc inside a pragma like `passC <nimc.html#passc-pragma>`_ or `passL
-  ## <nimc.html#passl-pragma>`_.
+  ## `gorge <#gorge,string,string,string>`_ is an alias for ``staticExec``.
+  ##
+  ## Note that you can use this proc inside a pragma like
+  ## `passC <nimc.html#passc-pragma>`_ or `passL <nimc.html#passl-pragma>`_.
   ##
   ## If ``cache`` is not empty, the results of ``staticExec`` are cached within
   ## the ``nimcache`` directory. Use ``--forceBuild`` to get rid of this caching
@@ -3488,60 +4020,71 @@ proc staticExec*(command: string, input = "", cache = ""): string {.
   ## used to determine whether the entry in the cache is still valid. You can
   ## use versioning information for ``cache``:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##     const stateMachine = staticExec("dfaoptimizer", "input", "0.8.0")
 
 proc gorgeEx*(command: string, input = "", cache = ""): tuple[output: string,
                                                               exitCode: int] =
-  ## Same as `gorge` but also returns the precious exit code.
+  ## Similar to `gorge <#gorge,string,string,string>`_ but also returns the
+  ## precious exit code.
   discard
 
 proc `+=`*[T: SomeInteger](x: var T, y: T) {.
   magic: "Inc", noSideEffect.}
-  ## Increments an integer
+  ## Increments an integer.
 
 proc `+=`*[T: enum|bool](x: var T, y: T) {.
   magic: "Inc", noSideEffect, deprecated: "use `inc` instead".}
+  ## **Deprecated since v0.20**: use `inc` instead.
 
 proc `-=`*[T: SomeInteger](x: var T, y: T) {.
   magic: "Dec", noSideEffect.}
-  ## Decrements an ordinal
+  ## Decrements an integer.
 
 proc `-=`*[T: enum|bool](x: var T, y: T) {.
   magic: "Dec", noSideEffect, deprecated: "0.20.0, use `dec` instead".}
+  ## **Deprecated since v0.20**: use `dec` instead.
 
 proc `*=`*[T: SomeInteger](x: var T, y: T) {.
   inline, noSideEffect.} =
-  ## Binary `*=` operator for ordinals
+  ## Binary `*=` operator for integers.
   x = x * y
 
 proc `+=`*[T: float|float32|float64] (x: var T, y: T) {.
   inline, noSideEffect.} =
-  ## Increments in place a floating point number
+  ## Increments in place a floating point number.
   x = x + y
 
 proc `-=`*[T: float|float32|float64] (x: var T, y: T) {.
   inline, noSideEffect.} =
-  ## Decrements in place a floating point number
+  ## Decrements in place a floating point number.
   x = x - y
 
 proc `*=`*[T: float|float32|float64] (x: var T, y: T) {.
   inline, noSideEffect.} =
-  ## Multiplies in place a floating point number
+  ## Multiplies in place a floating point number.
   x = x * y
 
 proc `/=`*(x: var float64, y: float64) {.inline, noSideEffect.} =
-  ## Divides in place a floating point number
+  ## Divides in place a floating point number.
   x = x / y
 
 proc `/=`*[T: float|float32](x: var T, y: T) {.inline, noSideEffect.} =
-  ## Divides in place a floating point number
+  ## Divides in place a floating point number.
   x = x / y
 
 proc `&=`*(x: var string, y: string) {.magic: "AppendStrStr", noSideEffect.}
+  ## Appends in place to a string.
+  ##
+  ## .. code-block:: Nim
+  ##   var a = "abc"
+  ##   a &= "de" # a <- "abcde"
+
 template `&=`*(x, y: typed) =
-  ## generic 'sink' operator for Nim. For files an alias for ``write``.
-  ## If not specialized further an alias for ``add``.
+  ## Generic 'sink' operator for Nim.
+  ##
+  ## For files an alias for ``write``.
+  ## If not specialized further, an alias for ``add``.
   add(x, y)
 when declared(File):
   template `&=`*(f: File, x: typed) = write(f, x)
@@ -3562,18 +4105,20 @@ when not defined(nimhygiene):
   {.pragma: inject.}
 
 proc shallow*[T](s: var seq[T]) {.noSideEffect, inline.} =
-  ## marks a sequence `s` as `shallow`:idx:. Subsequent assignments will not
-  ## perform deep copies of `s`. This is only useful for optimization
-  ## purposes.
+  ## Marks a sequence `s` as `shallow`:idx:. Subsequent assignments will not
+  ## perform deep copies of `s`.
+  ##
+  ## This is only useful for optimization purposes.
   if s.len == 0: return
   when not defined(JS) and not defined(nimscript):
     var s = cast[PGenericSeq](s)
     s.reserved = s.reserved or seqShallowFlag
 
 proc shallow*(s: var string) {.noSideEffect, inline.} =
-  ## marks a string `s` as `shallow`:idx:. Subsequent assignments will not
-  ## perform deep copies of `s`. This is only useful for optimization
-  ## purposes.
+  ## Marks a string `s` as `shallow`:idx:. Subsequent assignments will not
+  ## perform deep copies of `s`.
+  ##
+  ## This is only useful for optimization purposes.
   when not defined(JS) and not defined(nimscript) and not defined(gcDestructors):
     var s = cast[PGenericSeq](s)
     if s == nil:
@@ -3586,19 +4131,24 @@ type
   NimNodeObj = object
 
   NimNode* {.magic: "PNimrodNode".} = ref NimNodeObj
-    ## represents a Nim AST node. Macros operate on this type.
+    ## Represents a Nim AST node. Macros operate on this type.
 
 when false:
   template eval*(blk: typed): typed =
-    ## executes a block of code at compile time just as if it was a macro
-    ## optionally, the block can return an AST tree that will replace the
-    ## eval expression
+    ## Executes a block of code at compile time just as if it was a macro.
+    ##
+    ## Optionally, the block can return an AST tree that will replace the
+    ## eval expression.
     macro payload: typed {.gensym.} = blk
     payload()
 
 when hasAlloc or defined(nimscript):
   proc insert*(x: var string, item: string, i = 0.Natural) {.noSideEffect.} =
-    ## inserts `item` into `x` at position `i`.
+    ## Inserts `item` into `x` at position `i`.
+    ##
+    ## .. code-block:: Nim
+    ##   var a = "abc"
+    ##   a.insert("zz", 0) # a <- "zzabc"
     var xl = x.len
     setLen(x, xl+item.len)
     var j = xl-1
@@ -3631,8 +4181,9 @@ proc addEscapedChar*(s: var string, c: char) {.noSideEffect, inline.} =
   ##   by ``\xHH`` where ``HH`` is its hexadecimal value.
   ##
   ## The procedure has been designed so that its output is usable for many
-  ## different common syntaxes.
-  ## **Note**: This is not correct for producing Ansi C code!
+  ## diferent common syntaxes.
+  ##
+  ## **Note**: This is **not correct** for producing Ansi C code!
   case c
   of '\a': s.add "\\a" # \x07
   of '\b': s.add "\\b" # \x08
@@ -3655,11 +4206,12 @@ proc addEscapedChar*(s: var string, c: char) {.noSideEffect, inline.} =
 
 proc addQuoted*[T](s: var string, x: T) =
   ## Appends `x` to string `s` in place, applying quoting and escaping
-  ## if `x` is a string or char. See
-  ## `addEscapedChar <system.html#addEscapedChar>`_
+  ## if `x` is a string or char.
+  ##
+  ## See `addEscapedChar <#addEscapedChar,string,char>`_
   ## for the escaping scheme. When `x` is a string, characters in the
   ## range ``{\128..\255}`` are never escaped so that multibyte UTF-8
-  ## characters are untouched (note that this behavior is different from
+  ## characters are untouched (note that this behavior is diferent from
   ## ``addEscapedChar``).
   ##
   ## The Nim standard library uses this function on the elements of
@@ -3699,8 +4251,10 @@ proc addQuoted*[T](s: var string, x: T) =
 when hasAlloc:
   # XXX: make these the default (or implement the NilObject optimization)
   proc safeAdd*[T](x: var seq[T], y: T) {.noSideEffect, deprecated.} =
+    ## **Deprecated**
+    ##
     ## Adds ``y`` to ``x`` unless ``x`` is not yet initialized; in that case,
-    ## ``x`` becomes ``@[y]``
+    ## ``x`` becomes ``@[y]``.
     when defined(nimNoNilSeqs):
       x.add(y)
     else:
@@ -3708,7 +4262,9 @@ when hasAlloc:
       else: x.add(y)
 
   proc safeAdd*(x: var string, y: char) {.noSideEffect, deprecated.} =
-    ## Adds ``y`` to ``x``. If ``x`` is ``nil`` it is initialized to ``""``
+    ## **Deprecated**
+    ##
+    ## Adds ``y`` to ``x``. If ``x`` is ``nil`` it is initialized to ``""``.
     when defined(nimNoNilSeqs):
       x.add(y)
     else:
@@ -3716,8 +4272,10 @@ when hasAlloc:
       x.add(y)
 
   proc safeAdd*(x: var string, y: string) {.noSideEffect, deprecated.} =
+    ## **Deprecated**
+    ##
     ## Adds ``y`` to ``x`` unless ``x`` is not yet initalized; in that
-    ## case, ``x`` becomes ``y``
+    ## case, ``x`` becomes ``y``.
     when defined(nimNoNilSeqs):
       x.add(y)
     else:
@@ -3725,13 +4283,15 @@ when hasAlloc:
       else: x.add(y)
 
 proc locals*(): RootObj {.magic: "Plugin", noSideEffect.} =
-  ## generates a tuple constructor expression listing all the local variables
-  ## in the current scope. This is quite fast as it does not rely
+  ## Generates a tuple constructor expression listing all the local variables
+  ## in the current scope.
+  ##
+  ## This is quite fast as it does not rely
   ## on any debug or runtime information. Note that in contrast to what
-  ## the official signature says, the return type is not ``RootObj`` but a
+  ## the official signature says, the return type is *not* ``RootObj`` but a
   ## tuple of a structure that depends on the current scope. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   proc testLocals() =
   ##     var
   ##       a = "something"
@@ -3752,7 +4312,8 @@ when hasAlloc and not defined(nimscript) and not defined(JS) and
     not defined(gcDestructors):
   # XXX how to implement 'deepCopy' is an open problem.
   proc deepCopy*[T](x: var T, y: T) {.noSideEffect, magic: "DeepCopy".} =
-    ## performs a deep copy of `y` and copies it into `x`.
+    ## Performs a deep copy of `y` and copies it into `x`.
+    ##
     ## This is also used by the code generator
     ## for the implementation of ``spawn``.
     discard
@@ -3764,23 +4325,24 @@ when hasAlloc and not defined(nimscript) and not defined(JS) and
   include "system/deepcopy"
 
 proc procCall*(x: untyped) {.magic: "ProcCall", compileTime.} =
-  ## special magic to prohibit dynamic binding for `method`:idx: calls.
+  ## Special magic to prohibit dynamic binding for `method`:idx: calls.
   ## This is similar to `super`:idx: in ordinary OO languages.
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   # 'someMethod' will be resolved fully statically:
   ##   procCall someMethod(a, b)
   discard
 
 proc xlen*(x: string): int {.magic: "XLenStr", noSideEffect,
                              deprecated: "use len() instead".} =
-  ## **Deprecated since version 0.18.1**. Use len() instead.
+  ## **Deprecated since version 0.18.1**. Use `len()` instead.
   discard
 proc xlen*[T](x: seq[T]): int {.magic: "XLenSeq", noSideEffect,
                                 deprecated: "use len() instead".} =
-  ## returns the length of a sequence or a string without testing for 'nil'.
+  ## **Deprecated since version 0.18.1**. Use `len()` instead.
+  ##
+  ## Returns the length of a sequence or a string without testing for 'nil'.
   ## This is an optimization that rarely makes sense.
-  ## **Deprecated since version 0.18.1**. Use len() instead.
   discard
 
 
@@ -3812,7 +4374,7 @@ template closureScope*(body: untyped): untyped =
   ## Useful when creating a closure in a loop to capture local loop variables by
   ## their current iteration values. Example:
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##   var myClosure : proc()
   ##   # without closureScope:
   ##   for i in 0 .. 5:
@@ -3832,7 +4394,7 @@ template closureScope*(body: untyped): untyped =
 template once*(body: untyped): untyped =
   ## Executes a block of code only once (the first time the block is reached).
   ##
-  ## .. code-block:: nim
+  ## .. code-block:: Nim
   ##
   ##  proc draw(t: Triangle) =
   ##    once:
@@ -3849,6 +4411,20 @@ template once*(body: untyped): untyped =
 {.pop.} #{.push warning[GcMem]: off, warning[Uninit]: off.}
 
 proc substr*(s: string, first, last: int): string =
+  ## Copies a slice of `s` into a new string and returns this new
+  ## string.
+  ##
+  ## The bounds `first` and `last` denote the indices of
+  ## the first and last characters that shall be copied. If ``last``
+  ## is omitted, it is treated as ``high(s)``. If ``last >= s.len``, ``s.len``
+  ## is used instead: This means ``substr`` can also be used to `cut`:idx:
+  ## or `limit`:idx: a string's length.
+  runnableExamples:
+    let a = "abcdefgh"
+    assert a.substr(2, 5) == "cdef"
+    assert a.substr(2) == "cdefgh"
+    assert a.substr(5, 99) == "fgh"
+
   let first = max(first, 0)
   let L = max(min(last, high(s)) - first + 1, 0)
   result = newString(L)
@@ -3856,12 +4432,6 @@ proc substr*(s: string, first, last: int): string =
     result[i] = s[i+first]
 
 proc substr*(s: string, first = 0): string =
-  ## copies a slice of `s` into a new string and returns this new
-  ## string. The bounds `first` and `last` denote the indices of
-  ## the first and last characters that shall be copied. If ``last``
-  ## is omitted, it is treated as ``high(s)``. If ``last >= s.len``, ``s.len``
-  ## is used instead: This means ``substr`` can also be used to `cut`:idx:
-  ## or `limit`:idx: a string's length.
   result = substr(s, first, high(s))
 
 when defined(nimconfig):
@@ -3887,12 +4457,14 @@ when not defined(js):
     magic: "Slice".}
 
 type
-  ForLoopStmt* {.compilerProc.} = object ## special type that marks a macro
-                                         ## as a `for-loop macro`:idx:
+  ForLoopStmt* {.compilerProc.} = object ## \
+    ## A special type that marks a macro as a `for-loop macro`:idx:.
+    ## See `"For loop macros" <manual.html#macros-for-loop-macros>`_.
 
 when defined(genode):
   var componentConstructHook*: proc (env: GenodeEnv) {.nimcall.}
       ## Hook into the Genode component bootstrap process.
+      ##
       ## This hook is called after all globals are initialized.
       ## When this hook is set the component will not automatically exit,
       ## call ``quit`` explicitly to do so. This is the only available method
diff --git a/lib/system/assertions.nim b/lib/system/assertions.nim
index 42a5b61d7..e0e901a97 100644
--- a/lib/system/assertions.nim
+++ b/lib/system/assertions.nim
@@ -38,7 +38,7 @@ template assert*(cond: untyped, msg = "") =
   assertImpl(cond, msg, expr, compileOption("assertions"))
 
 template doAssert*(cond: untyped, msg = "") =
-  ## same as ``assert`` but is always turned on regardless of ``--assertions``
+  ## Similar to ``assert`` but is always turned on regardless of ``--assertions``.
   const expr = astToStr(cond)
   assertImpl(cond, msg, expr, true)
 
diff --git a/lib/system/excpt.nim b/lib/system/excpt.nim
index cb2cda214..38eb49397 100644
--- a/lib/system/excpt.nim
+++ b/lib/system/excpt.nim
@@ -14,7 +14,7 @@ var
   errorMessageWriter*: (proc(msg: string) {.tags: [WriteIOEffect], benign,
                                             nimcall.})
     ## Function that will be called
-    ## instead of stdmsg.write when printing stacktrace.
+    ## instead of `stdmsg.write` when printing stacktrace.
     ## Unstable API.
 
 proc c_fwrite(buf: pointer, size, n: csize, f: CFilePtr): cint {.
@@ -331,8 +331,9 @@ else:
   proc stackTraceAvailable*(): bool = result = false
 
 var onUnhandledException*: (proc (errorMsg: string) {.
-  nimcall.}) ## set this error \
+  nimcall.}) ## Set this error \
   ## handler to override the existing behaviour on an unhandled exception.
+  ##
   ## The default is to write a stacktrace to ``stderr`` and then call ``quit(1)``.
   ## Unstable API.
 
diff --git a/lib/system/iterators.nim b/lib/system/iterators.nim
index 2812db69e..1054d1e0c 100644
--- a/lib/system/iterators.nim
+++ b/lib/system/iterators.nim
@@ -1,19 +1,19 @@
 iterator items*[T](a: openArray[T]): T {.inline.} =
-  ## iterates over each item of `a`.
+  ## Iterates over each item of `a`.
   var i = 0
   while i < len(a):
     yield a[i]
     inc(i)
 
 iterator mitems*[T](a: var openArray[T]): var T {.inline.} =
-  ## iterates over each item of `a` so that you can modify the yielded value.
+  ## Iterates over each item of `a` so that you can modify the yielded value.
   var i = 0
   while i < len(a):
     yield a[i]
     inc(i)
 
 iterator items*[IX, T](a: array[IX, T]): T {.inline.} =
-  ## iterates over each item of `a`.
+  ## Iterates over each item of `a`.
   var i = low(IX)
   if i <= high(IX):
     while true:
@@ -22,7 +22,7 @@ iterator items*[IX, T](a: array[IX, T]): T {.inline.} =
       inc(i)
 
 iterator mitems*[IX, T](a: var array[IX, T]): var T {.inline.} =
-  ## iterates over each item of `a` so that you can modify the yielded value.
+  ## Iterates over each item of `a` so that you can modify the yielded value.
   var i = low(IX)
   if i <= high(IX):
     while true:
@@ -31,7 +31,7 @@ iterator mitems*[IX, T](a: var array[IX, T]): var T {.inline.} =
       inc(i)
 
 iterator items*[T](a: set[T]): T {.inline.} =
-  ## iterates over each element of `a`. `items` iterates only over the
+  ## Iterates over each element of `a`. `items` iterates only over the
   ## elements that are really in the set (and not over the ones the set is
   ## able to hold).
   var i = low(T).int
@@ -40,7 +40,7 @@ iterator items*[T](a: set[T]): T {.inline.} =
     inc(i)
 
 iterator items*(a: cstring): char {.inline.} =
-  ## iterates over each item of `a`.
+  ## Iterates over each item of `a`.
   when defined(js):
     var i = 0
     var L = len(a)
@@ -54,32 +54,32 @@ iterator items*(a: cstring): char {.inline.} =
       inc(i)
 
 iterator mitems*(a: var cstring): var char {.inline.} =
-  ## iterates over each item of `a` so that you can modify the yielded value.
+  ## Iterates over each item of `a` so that you can modify the yielded value.
   var i = 0
   while a[i] != '\0':
     yield a[i]
     inc(i)
 
 iterator items*(E: typedesc[enum]): E =
-  ## iterates over the values of the enum ``E``.
+  ## Iterates over the values of the enum ``E``.
   for v in low(E)..high(E):
     yield v
 
 iterator items*[T](s: HSlice[T, T]): T =
-  ## iterates over the slice `s`, yielding each value between `s.a` and `s.b`
+  ## Iterates over the slice `s`, yielding each value between `s.a` and `s.b`
   ## (inclusively).
   for x in s.a..s.b:
     yield x
 
 iterator pairs*[T](a: openArray[T]): tuple[key: int, val: T] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   var i = 0
   while i < len(a):
     yield (i, a[i])
     inc(i)
 
 iterator mpairs*[T](a: var openArray[T]): tuple[key:int, val:var T]{.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   ## ``a[index]`` can be modified.
   var i = 0
   while i < len(a):
@@ -87,7 +87,7 @@ iterator mpairs*[T](a: var openArray[T]): tuple[key:int, val:var T]{.inline.} =
     inc(i)
 
 iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   var i = low(IX)
   if i <= high(IX):
     while true:
@@ -96,7 +96,7 @@ iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} =
       inc(i)
 
 iterator mpairs*[IX, T](a:var array[IX, T]):tuple[key:IX,val:var T] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   ## ``a[index]`` can be modified.
   var i = low(IX)
   if i <= high(IX):
@@ -106,14 +106,14 @@ iterator mpairs*[IX, T](a:var array[IX, T]):tuple[key:IX,val:var T] {.inline.} =
       inc(i)
 
 iterator pairs*[T](a: seq[T]): tuple[key: int, val: T] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   var i = 0
   while i < len(a):
     yield (i, a[i])
     inc(i)
 
 iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   ## ``a[index]`` can be modified.
   var i = 0
   while i < len(a):
@@ -121,14 +121,14 @@ iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} =
     inc(i)
 
 iterator pairs*(a: string): tuple[key: int, val: char] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   var i = 0
   while i < len(a):
     yield (i, a[i])
     inc(i)
 
 iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   ## ``a[index]`` can be modified.
   var i = 0
   while i < len(a):
@@ -136,22 +136,23 @@ iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} =
     inc(i)
 
 iterator pairs*(a: cstring): tuple[key: int, val: char] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   var i = 0
   while a[i] != '\0':
     yield (i, a[i])
     inc(i)
 
 iterator mpairs*(a: var cstring): tuple[key: int, val: var char] {.inline.} =
-  ## iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
+  ## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs.
   ## ``a[index]`` can be modified.
   var i = 0
   while a[i] != '\0':
     yield (i, a[i])
     inc(i)
 
+
 iterator items*[T](a: seq[T]): T {.inline.} =
-  ## iterates over each item of `a`.
+  ## Iterates over each item of `a`.
   var i = 0
   let L = len(a)
   while i < L:
@@ -160,7 +161,7 @@ iterator items*[T](a: seq[T]): T {.inline.} =
     assert(len(a) == L, "seq modified while iterating over it")
 
 iterator mitems*[T](a: var seq[T]): var T {.inline.} =
-  ## iterates over each item of `a` so that you can modify the yielded value.
+  ## Iterates over each item of `a` so that you can modify the yielded value.
   var i = 0
   let L = len(a)
   while i < L:
@@ -169,7 +170,7 @@ iterator mitems*[T](a: var seq[T]): var T {.inline.} =
     assert(len(a) == L, "seq modified while iterating over it")
 
 iterator items*(a: string): char {.inline.} =
-  ## iterates over each item of `a`.
+  ## Iterates over each item of `a`.
   var i = 0
   let L = len(a)
   while i < L:
@@ -178,7 +179,7 @@ iterator items*(a: string): char {.inline.} =
     assert(len(a) == L, "string modified while iterating over it")
 
 iterator mitems*(a: var string): var char {.inline.} =
-  ## iterates over each item of `a` so that you can modify the yielded value.
+  ## Iterates over each item of `a` so that you can modify the yielded value.
   var i = 0
   let L = len(a)
   while i < L:
@@ -186,19 +187,21 @@ iterator mitems*(a: var string): var char {.inline.} =
     inc(i)
     assert(len(a) == L, "string modified while iterating over it")
 
+
 iterator fields*[T: tuple|object](x: T): RootObj {.
   magic: "Fields", noSideEffect.}
-  ## iterates over every field of `x`. Warning: This really transforms
-  ## the 'for' and unrolls the loop. The current implementation also has a bug
+  ## Iterates over every field of `x`.
+  ##
+  ## **Warning**: This really transforms the 'for' and unrolls the loop.
+  ## The current implementation also has a bug
   ## that affects symbol binding in the loop body.
-
 iterator fields*[S:tuple|object, T:tuple|object](x: S, y: T): tuple[a,b: untyped] {.
   magic: "Fields", noSideEffect.}
-  ## iterates over every field of `x` and `y`.
-  ## Warning: This is really transforms the 'for' and unrolls the loop.
+  ## Iterates over every field of `x` and `y`.
+  ##
+  ## **Warning**: This is really transforms the 'for' and unrolls the loop.
   ## The current implementation also has a bug that affects symbol binding
   ## in the loop body.
- 
 iterator fieldPairs*[T: tuple|object](x: T): RootObj {.
   magic: "FieldPairs", noSideEffect.}
   ## Iterates over every field of `x` returning their name and value.
@@ -209,7 +212,6 @@ iterator fieldPairs*[T: tuple|object](x: T): RootObj {.
   ## operator <manual.html#generics-is-operator>`_. Example:
   ##
   ## .. code-block:: Nim
-  ##
   ##   type
   ##     Custom = object
   ##       foo: string
@@ -230,14 +232,17 @@ iterator fieldPairs*[T: tuple|object](x: T): RootObj {.
   ## picking the appropriate code to a secondary proc which you overload for
   ## each field type and pass the `value` to.
   ##
-  ## Warning: This really transforms the 'for' and unrolls the loop. The
+  ## **Warning**: This really transforms the 'for' and unrolls the loop. The
   ## current implementation also has a bug that affects symbol binding in the
   ## loop body.
 
 iterator fieldPairs*[S: tuple|object, T: tuple|object](x: S, y: T): tuple[
   a, b: untyped] {.
   magic: "FieldPairs", noSideEffect.}
-  ## iterates over every field of `x` and `y`.
-  ## Warning: This really transforms the 'for' and unrolls the loop.
+  ## Iterates over every field of `x` and `y`.
+  ##
+  ## **Warning**: This really transforms the 'for' and unrolls the loop.
   ## The current implementation also has a bug that affects symbol binding
   ## in the loop body.
+
+
diff --git a/lib/system/strmantle.nim b/lib/system/strmantle.nim
index 3c681fc53..548dacd22 100644
--- a/lib/system/strmantle.nim
+++ b/lib/system/strmantle.nim
@@ -41,6 +41,13 @@ proc hashString(s: string): int {.compilerproc.} =
   result = h
 
 proc add*(result: var string; x: int64) =
+  ## Converts integer to its string representation and appends it to `result`.
+  ##
+  ## .. code-block:: Nim
+  ##   var
+  ##     a = "123"
+  ##     b = 45
+  ##   a.add(b) # a <- "12345"
   let base = result.len
   setLen(result, base + sizeof(x)*4)
   var i = 0
@@ -64,6 +71,13 @@ proc nimIntToStr(x: int): string {.compilerRtl.} =
   result.add x
 
 proc add*(result: var string; x: float) =
+  ## Converts float to its string representation and appends it to `result`.
+  ##
+  ## .. code-block:: Nim
+  ##   var
+  ##     a = "123"
+  ##     b = 45.67
+  ##   a.add(b) # a <- "12345.67"
   when nimvm:
     result.add $x
   else: