various small documentation improvements (#18602)

13 files changed, 123 insertions, 97 deletions

diff --git a/lib/pure/asyncdispatch.nim b/lib/pure/asyncdispatch.nim
index d98ca77df..955e66f6b 100644
--- a/lib/pure/asyncdispatch.nim
+++ b/lib/pure/asyncdispatch.nim
@@ -42,12 +42,12 @@
 ##
 ## Code to read some data from a socket may look something like this:
 ##
-##   .. code-block:: Nim
-##      var future = socket.recv(100)
-##      future.addCallback(
-##        proc () =
-##          echo(future.read)
-##      )
+## .. code-block:: Nim
+##    var future = socket.recv(100)
+##    future.addCallback(
+##      proc () =
+##        echo(future.read)
+##    )
 ##
 ## All asynchronous functions returning a `Future` will not block. They
 ## will not however return immediately. An asynchronous function will have
@@ -104,20 +104,20 @@
 ## The most reliable way to handle exceptions is to use `yield` on a future
 ## then check the future's `failed` property. For example:
 ##
-##   .. code-block:: Nim
-##     var future = sock.recv(100)
-##     yield future
-##     if future.failed:
-##       # Handle exception
+## .. code-block:: Nim
+##   var future = sock.recv(100)
+##   yield future
+##   if future.failed:
+##     # Handle exception
 ##
 ## The `async` procedures also offer limited support for the try statement.
 ##
-##    .. code-block:: Nim
-##      try:
-##        let data = await sock.recv(100)
-##        echo("Received ", data)
-##      except:
-##        # Handle exception
+## .. code-block:: Nim
+##   try:
+##     let data = await sock.recv(100)
+##     echo("Received ", data)
+##   except:
+##     # Handle exception
 ##
 ## Unfortunately the semantics of the try statement may not always be correct,
 ## and occasionally the compilation may fail altogether.
diff --git a/lib/pure/collections/deques.nim b/lib/pure/collections/deques.nim
index fe9ceca1e..ecdf199d2 100644
--- a/lib/pure/collections/deques.nim
+++ b/lib/pure/collections/deques.nim
@@ -10,8 +10,9 @@
 ## An implementation of a `deque`:idx: (double-ended queue).
 ## The underlying implementation uses a `seq`.
 ##
-## Note that none of the procs that get an individual value from the deque should be used
-## on an empty deque.
+## .. note:: None of the procs that get an individual value from the deque should be used
+##   on an empty deque.
+##
 ## If compiled with the `boundChecks` option, those procs will raise an `IndexDefect`
 ## on such access. This should not be relied upon, as `-d:danger` or `--checks:off` will
 ## disable those checks and then the procs may return garbage or crash the program.
@@ -198,7 +199,7 @@ iterator items*[T](deq: Deque[T]): lent T =
   ## Yields every element of `deq`.
   ##
   ## **See also:**
-  ## * `mitems iterator <#mitems,Deque[T]>`_
+  ## * `mitems iterator <#mitems.i,Deque[T]>`_
   runnableExamples:
     from std/sequtils import toSeq
 
@@ -214,7 +215,7 @@ iterator mitems*[T](deq: var Deque[T]): var T =
   ## Yields every element of `deq`, which can be modified.
   ##
   ## **See also:**
-  ## * `items iterator <#items,Deque[T]>`_
+  ## * `items iterator <#items.i,Deque[T]>`_
   runnableExamples:
     var a = [10, 20, 30, 40, 50].toDeque
     assert $a == "[10, 20, 30, 40, 50]"
@@ -274,7 +275,7 @@ proc addFirst*[T](deq: var Deque[T], item: sink T) =
   ## Adds an `item` to the beginning of `deq`.
   ##
   ## **See also:**
-  ## * `addLast proc <#addLast,Deque[T],T>`_
+  ## * `addLast proc <#addLast,Deque[T],sinkT>`_
   runnableExamples:
     var a = initDeque[int]()
     for i in 1 .. 5:
@@ -290,7 +291,7 @@ proc addLast*[T](deq: var Deque[T], item: sink T) =
   ## Adds an `item` to the end of `deq`.
   ##
   ## **See also:**
-  ## * `addFirst proc <#addFirst,Deque[T],T>`_
+  ## * `addFirst proc <#addFirst,Deque[T],sinkT>`_
   runnableExamples:
     var a = initDeque[int]()
     for i in 1 .. 5:
diff --git a/lib/pure/collections/intsets.nim b/lib/pure/collections/intsets.nim
index 05e5addcc..765a23e97 100644
--- a/lib/pure/collections/intsets.nim
+++ b/lib/pure/collections/intsets.nim
@@ -8,7 +8,7 @@
 #
 
 ## Specialization of the generic `packedsets module <packedsets.html>`_
-## for ordinal sparse sets.
+## (see its documentation for more examples) for ordinal sparse sets.
 
 import std/private/since
 import std/packedsets
diff --git a/lib/pure/collections/sharedlist.nim b/lib/pure/collections/sharedlist.nim
index 79f2391f6..73e147e05 100644
--- a/lib/pure/collections/sharedlist.nim
+++ b/lib/pure/collections/sharedlist.nim
@@ -35,7 +35,7 @@ template withLock(t, x: untyped) =
   release(t.lock)
 
 proc iterAndMutate*[A](x: var SharedList[A]; action: proc(x: A): bool) =
-  ## Iterates over the list. If 'action' returns true, the
+  ## Iterates over the list. If `action` returns true, the
   ## current item is removed from the list.
   ##
   ## .. warning:: It may not preserve the element order after some modifications.
diff --git a/lib/pure/collections/tables.nim b/lib/pure/collections/tables.nim
index 403345755..2695f3693 100644
--- a/lib/pure/collections/tables.nim
+++ b/lib/pure/collections/tables.nim
@@ -136,6 +136,8 @@ runnableExamples:
 ## a more complex object as a key you will be greeted by a strange compiler
 ## error:
 ##
+## .. code::
+##
 ##   Error: type mismatch: got (Person)
 ##   but expected one of:
 ##   hashes.hash(x: openArray[A]): Hash
@@ -324,7 +326,7 @@ proc `[]`*[A, B](t: Table[A, B], key: A): B =
   ##   a default value (e.g. zero for int) if the key doesn't exist
   ## * `getOrDefault proc<#getOrDefault,Table[A,B],A,B>`_ to return
   ##   a custom value if the key doesn't exist
-  ## * `[]= proc<#[]=,Table[A,B],A,B>`_ for inserting a new
+  ## * `[]= proc<#[]=,Table[A,B],A,sinkB>`_ for inserting a new
   ##   (key, value) pair in the table
   ## * `hasKey proc<#hasKey,Table[A,B],A>`_ for checking if a key is in
   ##   the table
@@ -345,7 +347,7 @@ proc `[]`*[A, B](t: var Table[A, B], key: A): var B =
   ##   a default value (e.g. zero for int) if the key doesn't exist
   ## * `getOrDefault proc<#getOrDefault,Table[A,B],A,B>`_ to return
   ##   a custom value if the key doesn't exist
-  ## * `[]= proc<#[]=,Table[A,B],A,B>`_ for inserting a new
+  ## * `[]= proc<#[]=,Table[A,B],A,sinkB>`_ for inserting a new
   ##   (key, value) pair in the table
   ## * `hasKey proc<#hasKey,Table[A,B],A>`_ for checking if a key is in
   ##   the table
@@ -488,7 +490,7 @@ proc add*[A, B](t: var Table[A, B], key: A, val: sink B) {.deprecated:
   ##
   ## **This can introduce duplicate keys into the table!**
   ##
-  ## Use `[]= proc<#[]=,Table[A,B],A,B>`_ for inserting a new
+  ## Use `[]= proc<#[]=,Table[A,B],A,sinkB>`_ for inserting a new
   ## (key, value) pair in the table without introducing duplicates.
   addImpl(enlarge)
 
@@ -499,7 +501,8 @@ template tabCellHash(i)  = t.data[i].hcode
 proc del*[A, B](t: var Table[A, B], key: A) =
   ## Deletes `key` from hash table `t`. Does nothing if the key does not exist.
   ##
-  ## .. warning:: If duplicate keys were added, this may need to be called multiple times.
+  ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
+  ##   this may need to be called multiple times.
   ##
   ## See also:
   ## * `pop proc<#pop,Table[A,B],A,B>`_
@@ -519,7 +522,8 @@ proc pop*[A, B](t: var Table[A, B], key: A, val: var B): bool =
   ## mapping of the key. Otherwise, returns `false`, and the `val` is
   ## unchanged.
   ##
-  ## .. warning:: If duplicate keys were added, this may need to be called multiple times.
+  ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
+  ##   this may need to be called multiple times.
   ##
   ## See also:
   ## * `del proc<#del,Table[A,B],A>`_
@@ -1028,7 +1032,8 @@ proc add*[A, B](t: TableRef[A, B], key: A, val: sink B) {.deprecated:
 proc del*[A, B](t: TableRef[A, B], key: A) =
   ## Deletes `key` from hash table `t`. Does nothing if the key does not exist.
   ##
-  ## **If duplicate keys were added, this may need to be called multiple times.**
+  ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
+  ##   this may need to be called multiple times.
   ##
   ## See also:
   ## * `pop proc<#pop,TableRef[A,B],A,B>`_
@@ -1048,7 +1053,8 @@ proc pop*[A, B](t: TableRef[A, B], key: A, val: var B): bool =
   ## mapping of the key. Otherwise, returns `false`, and the `val` is
   ## unchanged.
   ##
-  ## **If duplicate keys were added, this may need to be called multiple times.**
+  ## .. warning:: If duplicate keys were added (via the now deprecated `add` proc),
+  ##   this may need to be called multiple times.
   ##
   ## See also:
   ## * `del proc<#del,TableRef[A,B],A>`_
diff --git a/lib/pure/net.nim b/lib/pure/net.nim
index c2e4810de..c0f9e1465 100644
--- a/lib/pure/net.nim
+++ b/lib/pure/net.nim
@@ -585,10 +585,10 @@ when defineSsl:
     ##
     ## CA certificates will be loaded, in the following order, from:
     ##
-    ##  - caFile, caDir, parameters, if set
-    ##  - if `verifyMode` is set to `CVerifyPeerUseEnvVars`,
-    ##    the SSL_CERT_FILE and SSL_CERT_DIR environment variables are used
-    ##  - a set of files and directories from the `ssl_certs <ssl_certs.html>`_ file.
+    ## - caFile, caDir, parameters, if set
+    ## - if `verifyMode` is set to `CVerifyPeerUseEnvVars`,
+    ##   the SSL_CERT_FILE and SSL_CERT_DIR environment variables are used
+    ## - a set of files and directories from the `ssl_certs <ssl_certs.html>`_ file.
     ##
     ## The last two parameters specify the certificate file path and the key file
     ## path, a server socket will most likely not work without these.
diff --git a/lib/pure/strformat.nim b/lib/pure/strformat.nim
index 872141383..746f01ace 100644
--- a/lib/pure/strformat.nim
+++ b/lib/pure/strformat.nim
@@ -142,12 +142,12 @@ An expression like `&"{key} is {value:arg} {{z}}"` is transformed into:
   temp
 
 Parts of the string that are enclosed in the curly braces are interpreted
-as Nim code, to escape a `{` or `}`, double it.
+as Nim code. To escape a `{` or `}`, double it.
 
-Within a curly expression,however, '{','}', must be escaped with a backslash.
+Within a curly expression, however, `{`, `}`, must be escaped with a backslash.
 
-To enable evaluating Nim expressions within curlies, inside parentheses
-colons do not need to be escaped.
+To enable evaluating Nim expressions within curlies, colons inside parentheses
+do not need to be escaped.
 ]##
 
 runnableExamples:
@@ -177,28 +177,28 @@ The general form of a standard format specifier is::
 
 The square brackets `[]` indicate an optional element.
 
-The optional 'align' flag can be one of the following:
+The optional `align` flag can be one of the following:
 
-'<'
+`<`
     Forces the field to be left-aligned within the available
     space. (This is the default for strings.)
 
-'>'
+`>`
     Forces the field to be right-aligned within the available space.
     (This is the default for numbers.)
 
-'^'
+`^`
     Forces the field to be centered within the available space.
 
 Note that unless a minimum field width is defined, the field width
 will always be the same size as the data to fill it, so that the alignment
 option has no meaning in this case.
 
-The optional 'fill' character defines the character to be used to pad
+The optional `fill` character defines the character to be used to pad
 the field to the minimum width. The fill character, if present, must be
 followed by an alignment flag.
 
-The 'sign' option is only valid for numeric types, and can be one of the following:
+The `sign` option is only valid for numeric types, and can be one of the following:
 
 =================        ====================================================
   Sign                   Meaning
@@ -211,22 +211,22 @@ The 'sign' option is only valid for numeric types, and can be one of the followi
                          positive numbers.
 =================        ====================================================
 
-If the '#' character is present, integers use the 'alternate form' for formatting.
+If the `#` character is present, integers use the 'alternate form' for formatting.
 This means that binary, octal and hexadecimal output will be prefixed
-with '0b', '0o' and '0x', respectively.
+with `0b`, `0o` and `0x`, respectively.
 
-'width' is a decimal integer defining the minimum field width. If not specified,
+`width` is a decimal integer defining the minimum field width. If not specified,
 then the field width will be determined by the content.
 
-If the width field is preceded by a zero ('0') character, this enables
+If the width field is preceded by a zero (`0`) character, this enables
 zero-padding.
 
-The 'precision' is a decimal number indicating how many digits should be displayed
+The `precision` is a decimal number indicating how many digits should be displayed
 after the decimal point in a floating point conversion. For non-numeric types the
 field indicates the maximum field size - in other words, how many characters will
 be used from the field content. The precision is ignored for integer conversions.
 
-Finally, the 'type' determines how the data should be presented.
+Finally, the `type` determines how the data should be presented.
 
 The available integer presentation types are:
 
@@ -240,7 +240,7 @@ The available integer presentation types are:
                          lower-case letters for the digits above 9.
 `X`                      Hex format. Outputs the number in base 16, using
                          uppercase letters for the digits above 9.
-(None)                   The same as 'd'.
+(None)                   The same as `d`.
 =================        ====================================================
 
 The available floating point presentation types are:
@@ -249,21 +249,21 @@ The available floating point presentation types are:
   Type                   Result
 =================        ====================================================
 `e`                      Exponent notation. Prints the number in scientific
-                         notation using the letter 'e' to indicate the
+                         notation using the letter `e` to indicate the
                          exponent.
-`E`                      Exponent notation. Same as 'e' except it converts
+`E`                      Exponent notation. Same as `e` except it converts
                          the number to uppercase.
 `f`                      Fixed point. Displays the number as a fixed-point
                          number.
-`F`                      Fixed point. Same as 'f' except it converts the
+`F`                      Fixed point. Same as `f` except it converts the
                          number to uppercase.
 `g`                      General format. This prints the number as a
                          fixed-point number, unless the number is too
-                         large, in which case it switches to 'e'
+                         large, in which case it switches to `e`
                          exponent notation.
-`G`                      General format. Same as 'g' except it switches to 'E'
+`G`                      General format. Same as `g` except it switches to `E`
                          if the number gets to large.
-(None)                   Similar to 'g', except that it prints at least one
+(None)                   Similar to `g`, except that it prints at least one
                          digit after the decimal point.
 =================        ====================================================
 
diff --git a/lib/pure/strscans.nim b/lib/pure/strscans.nim
index 73b53e3d6..291af7408 100644
--- a/lib/pure/strscans.nim
+++ b/lib/pure/strscans.nim
@@ -52,7 +52,7 @@ substrings starting with ``$``. These constructions are available:
 =================   ========================================================
 
 Even though ``$*`` and ``$+`` look similar to the regular expressions ``.*``
-and ``.+`` they work quite differently, there is no non-deterministic
+and ``.+``, they work quite differently. There is no non-deterministic
 state machine involved and the matches are non-greedy. ``[$*]``
 matches ``[xyz]`` via ``parseutils.parseUntil``.
 
diff --git a/lib/std/enumutils.nim b/lib/std/enumutils.nim
index 09cf24f51..6269950c7 100644
--- a/lib/std/enumutils.nim
+++ b/lib/std/enumutils.nim
@@ -79,8 +79,14 @@ macro enumNames(a: typed): untyped =
 iterator items*[T: HoleyEnum](E: typedesc[T]): T =
   ## Iterates over an enum with holes.
   runnableExamples:
-    type A = enum a0 = 2, a1 = 4, a2
-    type B[T] = enum b0 = 2, b1 = 4
+    type
+      A = enum
+        a0 = 2
+        a1 = 4
+        a2
+      B[T] = enum
+        b0 = 2
+        b1 = 4
     from std/sequtils import toSeq
     assert A.toSeq == [a0, a1, a2]
     assert B[float].toSeq == [B[float].b0, B[float].b1]
@@ -130,9 +136,19 @@ template symbolRank*[T: enum](a: T): int =
   ## for small enums, otherwise is `O(T.enumLen)`.
   runnableExamples:
     type
-      A = enum a0 = -3, a1 = 10, a2, a3 = (20, "f3Alt") # HoleyEnum
-      B = enum b0, b1, b2 # OrdinalEnum
-      C = enum c0 = 10, c1, c2 # OrdinalEnum
+      A = enum # HoleyEnum
+        a0 = -3
+        a1 = 10
+        a2
+        a3 = (20, "f3Alt")
+      B = enum # OrdinalEnum
+        b0
+        b1
+        b2
+      C = enum # OrdinalEnum
+        c0 = 10
+        c1
+        c2
     assert a2.symbolRank == 2
     assert b2.symbolRank == 2
     assert c2.symbolRank == 2
@@ -156,7 +172,10 @@ func symbolName*[T: enum](a: T): string =
     assert b.symbolName == "b0"
     assert $b == "kb0"
     static: assert B.high.symbolName == "b2"
-    type C = enum c0 = -3, c1 = 4, c2 = 20 # HoleyEnum
+    type C = enum # HoleyEnum
+      c0 = -3
+      c1 = 4
+      c2 = 20
     assert c1.symbolName == "c1"
   const names = enumNames(T)
   names[a.symbolRank]
diff --git a/lib/std/packedsets.nim b/lib/std/packedsets.nim
index e209d2aae..b2ee917eb 100644
--- a/lib/std/packedsets.nim
+++ b/lib/std/packedsets.nim
@@ -12,10 +12,10 @@
 ##
 ## Supports any Ordinal type.
 ##
-## **Note**: Currently the assignment operator `=` for `PackedSet[A]`
-## performs some rather meaningless shallow copy. Since Nim currently does
-## not allow the assignment operator to be overloaded, use the `assign proc
-## <#assign,PackedSet[A],PackedSet[A]>`_ to get a deep copy.
+## .. note:: Currently the assignment operator `=` for `PackedSet[A]`
+##   performs some rather meaningless shallow copy. Since Nim currently does
+##   not allow the assignment operator to be overloaded, use the `assign proc
+##   <#assign,PackedSet[A],PackedSet[A]>`_ to get a deep copy.
 ##
 ## See also
 ## ========
diff --git a/lib/system/threads.nim b/lib/system/threads.nim
index 2b5eb07fd..a9006b0c5 100644
--- a/lib/system/threads.nim
+++ b/lib/system/threads.nim
@@ -11,7 +11,7 @@
 ##
 ## **Note**: This is part of the system module. Do not import it directly.
 ## To activate thread support you need to compile
-## with the `--threads:on` command line switch.
+## with the `--threads:on`:option: command line switch.
 ##
 ## Nim's memory model for threads is quite different from other common
 ## programming languages (C, Pascal): Each thread has its own
diff --git a/lib/system_overview.rst b/lib/system_overview.rst
index d6cbe1a35..df22697e0 100644
--- a/lib/system_overview.rst
+++ b/lib/system_overview.rst
@@ -48,27 +48,27 @@ Proc                              Usage
 Seqs
 ----
 
-==============================================     ==========================================
-Proc                                               Usage
-==============================================     ==========================================
-`newSeq<#newSeq>`_                                 Create a new sequence of a given length
-`newSeqOfCap<#newSeqOfCap,Natural>`_               Create a new sequence with zero length
-                                                   and a given capacity
-`setLen<#setLen,seq[T],Natural>`_                  Set the length of a sequence
-`len<#len,seq[T]>`_                                Return the length of a sequence
-`@<#@,openArray[T]>`_                              Turn an array into a sequence
-`add<#add,seq[T],sinkT>`_                          Add an item to the sequence
-`insert<#insert,seq[T],sinkT>`_                    Insert an item at a specific position
-`delete<#delete,seq[T],Natural>`_                  Delete an item while preserving the
-                                                   order of elements (`O(n)` operation)
-`del<#del,seq[T],Natural>`_                        `O(1)` removal, doesn't preserve the order
-`pop<#pop,seq[T]>`_                                Remove and return last item of a sequence
-`x & y<#&,seq[T],seq[T]>`_                         Concatenate two sequences
-`x[a .. b]<#[],openArray[T],HSlice[U,V]>`_         Slice of a sequence (both ends included)
-`x[a .. ^b]<#[],openArray[T],HSlice[U,V]>`_        Slice of a sequence but `b` is a 
-                                                   reversed index (both ends included)
-`x[a ..\< b]<#[],openArray[T],HSlice[U,V]>`_       Slice of a sequence (excluded upper bound)
-==============================================     ==========================================
+=============================================================  ==========================================
+Proc                                                           Usage
+=============================================================  ==========================================
+`newSeq<#newSeq>`_                                             Create a new sequence of a given length
+`newSeqOfCap<#newSeqOfCap,Natural>`_                           Create a new sequence with zero length
+                                                               and a given capacity
+`setLen<#setLen,seq[T],Natural>`_                              Set the length of a sequence
+`len<#len,seq[T]>`_                                            Return the length of a sequence
+`@<#@,openArray[T]>`_                                          Turn an array into a sequence
+`add<#add,seq[T],sinkT>`_                                      Add an item to the sequence
+`insert<#insert,seq[T],sinkT>`_                                Insert an item at a specific position
+`delete<#delete,seq[T],Natural>`_                              Delete an item while preserving the
+                                                               order of elements (`O(n)` operation)
+`del<#del,seq[T],Natural>`_                                    `O(1)` removal, doesn't preserve the order
+`pop<#pop,seq[T]>`_                                            Remove and return last item of a sequence
+`x & y<#&,seq[T],seq[T]>`_                                     Concatenate two sequences
+`x[a .. b]<#[],openArray[T],HSlice[U: Ordinal,V: Ordinal]>`_   Slice of a sequence (both ends included)
+`x[a .. ^b]<#[],openArray[T],HSlice[U: Ordinal,V: Ordinal]>`_  Slice of a sequence but `b` is a 
+                                                               reversed index (both ends included)
+`x[a ..< b]<#[],openArray[T],HSlice[U: Ordinal,V: Ordinal]>`_  Slice of a sequence (excluded upper bound)
+=============================================================  ==========================================
 
 **See also:**
 * `sequtils module <sequtils.html>`_ for operations on container
diff --git a/tests/stdlib/trst.nim b/tests/stdlib/trst.nim
index fc3ccbf4e..bc11f219c 100644
--- a/tests/stdlib/trst.nim
+++ b/tests/stdlib/trst.nim
@@ -182,9 +182,9 @@ suite "RST parsing":
   test "using .. as separator b/w directives and block quotes":
     check(dedent"""
         .. note:: someNote
-    
+
         ..
-    
+
           someBlockQuote""".toAst ==
       dedent"""
         rnInner
@@ -300,14 +300,14 @@ suite "RST indentation":
     let input1 = dedent"""
       .. code-block:: nim
           :test: "nim c $1"
-      
+
         template additive(typ: typedesc) =
           discard
       """
     let input2 = dedent"""
       .. code-block:: nim
         :test: "nim c $1"
-      
+
         template additive(typ: typedesc) =
           discard
       """
@@ -320,7 +320,7 @@ suite "RST indentation":
     let inputWrong = dedent"""
       .. code-block:: nim
        :test: "nim c $1"
-      
+
          template additive(typ: typedesc) =
            discard
       """