Use .. warning:: (#17320)

lib/posix/posix.nim

@@ -1048,16 +1048,16 @@ proc realpath*(name, resolved: cstring): cstring {.
 proc mkstemp*(tmpl: cstring): cint {.importc, header: "<stdlib.h>", sideEffect.}
   ## Creates a unique temporary file.
   ##
-  ## **Warning**: The `tmpl` argument is written to by `mkstemp` and thus
+  ## .. warning:: The `tmpl` argument is written to by `mkstemp` and thus
-  ## can't be a string literal. If in doubt make a copy of the cstring before
+  ##   can't be a string literal. If in doubt make a copy of the cstring before
-  ## passing it in.
+  ##   passing it in.
 
 proc mkstemps*(tmpl: cstring, suffixlen: int): cint {.importc, header: "<stdlib.h>", sideEffect.}
   ## Creates a unique temporary file.
   ##
-  ## **Warning**: The `tmpl` argument is written to by `mkstemps` and thus
+  ## .. warning:: The `tmpl` argument is written to by `mkstemps` and thus
-  ## can't be a string literal. If in doubt make a copy of the cstring before
+  ##   can't be a string literal. If in doubt make a copy of the cstring before
-  ## passing it in.
+  ##   passing it in.
 
 proc mkdtemp*(tmpl: cstring): pointer {.importc, header: "<stdlib.h>", sideEffect.}
 

lib/pure/asyncdispatch.nim

@@ -573,7 +573,7 @@ when defined(windows) or defined(nimdoc):
     ## will complete once all data has been sent.
     ##
     ## .. warning:: Use it with caution. If `buf` refers to GC'ed object,
-    ## you must use GC_ref/GC_unref calls to avoid early freeing of the buffer.
+    ##   you must use GC_ref/GC_unref calls to avoid early freeing of the buffer.
     verifyPresence(socket)
     var retFuture = newFuture[void]("send")
 

lib/pure/collections/tables.nim

@@ -2437,7 +2437,7 @@ proc sort*[A](t: var CountTable[A], order = SortOrder.Descending) =
   ## Sorts the count table so that, by default, the entry with the
   ## highest counter comes first.
   ##
-  ## **WARNING:** This is destructive! Once sorted, you must not modify `t` afterwards!
+  ## .. warning:: This is destructive! Once sorted, you must not modify `t` afterwards!
   ##
   ## You can use the iterators `pairs<#pairs.i,CountTable[A]>`_,
   ## `keys<#keys.i,CountTable[A]>`_, and `values<#values.i,CountTable[A]>`_

lib/pure/dynlib.nim

@@ -99,7 +99,7 @@ proc libCandidates*(s: string, dest: var seq[string]) =
 proc loadLibPattern*(pattern: string, globalSymbols = false): LibHandle =
   ## loads a library with name matching `pattern`, similar to what `dynlib`
   ## pragma does. Returns nil if the library could not be loaded.
-  ## Warning: this proc uses the GC and so cannot be used to load the GC.
+  ## .. warning:: this proc uses the GC and so cannot be used to load the GC.
   var candidates = newSeq[string]()
   libCandidates(pattern, candidates)
   for c in candidates:

lib/pure/includes/oserr.nim

@@ -102,11 +102,10 @@ proc osLastError*(): OSErrorCode {.sideEffect.} =
   ## OS call failed. The `OSErrorMsg` procedure can then be used to convert
   ## this code into a string.
   ##
-  ## **Warning**:
+  ## .. warning:: The behaviour of this procedure varies between Windows and POSIX systems.
-  ## The behaviour of this procedure varies between Windows and POSIX systems.
+  ##   On Windows some OS calls can reset the error code to `0` causing this
-  ## On Windows some OS calls can reset the error code to `0` causing this
+  ##   procedure to return `0`. It is therefore advised to call this procedure
-  ## procedure to return `0`. It is therefore advised to call this procedure
+  ##   immediately after an OS call fails. On POSIX systems this is not a problem.
-  ## immediately after an OS call fails. On POSIX systems this is not a problem.
   ##
   ## See also:
   ## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_

lib/pure/logging.nim

@@ -45,8 +45,8 @@
 ## ``levelThreshold`` field and the global log filter. The latter can be changed
 ## with the `setLogFilter proc<#setLogFilter,Level>`_.
 ##
-## **Warning:**
+## .. warning::
-## * For loggers that log to a console or to files, only error and fatal
+##   For loggers that log to a console or to files, only error and fatal
 ##   messages will cause their output buffers to be flushed immediately.
 ##   Use the `flushFile proc <io.html#flushFile,File>`_ to flush the buffer
 ##   manually if needed.
@@ -794,9 +794,9 @@ template fatal*(args: varargs[string, `$`]) =
 proc addHandler*(handler: Logger) =
   ## Adds a logger to the list of registered handlers.
   ##
-  ## **Warning:** The list of handlers is a thread-local variable. If the given
+  ## .. warning:: The list of handlers is a thread-local variable. If the given
-  ## handler will be used in multiple threads, this proc should be called in
+  ##   handler will be used in multiple threads, this proc should be called in
-  ## each of those threads.
+  ##   each of those threads.
   ##
   ## See also:
   ## * `getHandlers proc<#getHandlers>`_
@@ -820,10 +820,10 @@ proc setLogFilter*(lvl: Level) =
   ## individual logger's ``levelThreshold``. By default, all messages are
   ## logged.
   ##
-  ## **Warning:** The global log filter is a thread-local variable. If logging
+  ## .. warning:: The global log filter is a thread-local variable. If logging
-  ## is being performed in multiple threads, this proc should be called in each
+  ##   is being performed in multiple threads, this proc should be called in each
-  ## thread unless it is intended that different threads should log at different
+  ##   thread unless it is intended that different threads should log at different
-  ## logging levels.
+  ##   logging levels.
   ##
   ## See also:
   ## * `getLogFilter proc<#getLogFilter>`_

lib/pure/nativesockets.nim

@@ -280,7 +280,7 @@ proc getAddrInfo*(address: string, port: Port, domain: Domain = AF_INET,
                   protocol: Protocol = IPPROTO_TCP): ptr AddrInfo =
   ##
   ##
-  ## **Warning**: The resulting `ptr AddrInfo` must be freed using `freeAddrInfo`!
+  ## .. warning:: The resulting `ptr AddrInfo` must be freed using `freeAddrInfo`!
   var hints: AddrInfo
   result = nil
   hints.ai_family = toInt(domain)

lib/pure/net.nim

@@ -1445,7 +1445,7 @@ proc recv*(socket: Socket, data: var string, size: int, timeout = -1,
   ##
   ## **Note**: `data` must be initialised.
   ##
-  ## **Warning**: Only the `SafeDisconn` flag is currently supported.
+  ## .. warning:: Only the `SafeDisconn` flag is currently supported.
   data.setLen(size)
   result =
     if timeout == -1:
@@ -1480,7 +1480,7 @@ proc recv*(socket: Socket, size: int, timeout = -1,
   ## within the time specified a TimeoutError exception will be raised.
   ##
   ##
-  ## **Warning**: Only the `SafeDisconn` flag is currently supported.
+  ## .. warning:: Only the `SafeDisconn` flag is currently supported.
   result = newString(size)
   discard recv(socket, result, size, timeout, flags)
 
@@ -1523,7 +1523,7 @@ proc readLine*(socket: Socket, line: var string, timeout = -1,
   ## The `maxLength` parameter determines the maximum amount of characters
   ## that can be read. The result is truncated after that.
   ##
-  ## **Warning**: Only the `SafeDisconn` flag is currently supported.
+  ## .. warning:: Only the `SafeDisconn` flag is currently supported.
 
   template addNLIfEmpty() =
     if line.len == 0:
@@ -1579,7 +1579,7 @@ proc recvLine*(socket: Socket, timeout = -1,
   ## The `maxLength` parameter determines the maximum amount of characters
   ## that can be read. The result is truncated after that.
   ##
-  ## **Warning**: Only the `SafeDisconn` flag is currently supported.
+  ## .. warning:: Only the `SafeDisconn` flag is currently supported.
   result = ""
   readLine(socket, result, timeout, flags, maxLength)
 
@@ -1592,10 +1592,10 @@ proc recvFrom*(socket: Socket, data: var string, length: int,
   ## If an error occurs an OSError exception will be raised. Otherwise the return
   ## value will be the length of data received.
   ##
-  ## **Warning:** This function does not yet have a buffered implementation,
+  ## .. warning:: This function does not yet have a buffered implementation,
-  ## so when `socket` is buffered the non-buffered implementation will be
+  ##   so when `socket` is buffered the non-buffered implementation will be
-  ## used. Therefore if `socket` contains something in its buffer this
+  ##   used. Therefore if `socket` contains something in its buffer this
-  ## function will make no effort to return it.
+  ##   function will make no effort to return it.
   template adaptRecvFromToDomain(domain: Domain) =
     var addrLen = sizeof(sockAddress).SockLen
     result = recvfrom(socket.fd, cstring(data), length.cint, flags.cint,

lib/pure/os.nim

@@ -1458,8 +1458,8 @@ proc normalizePath*(path: var string) {.rtl, extern: "nos$1", tags: [].} =
   ## On relative paths, double dot (`..`) sequences are collapsed if possible.
   ## On absolute paths they are always collapsed.
   ##
-  ## Warning: URL-encoded and Unicode attempts at directory traversal are not detected.
+  ## .. warning:: URL-encoded and Unicode attempts at directory traversal are not detected.
-  ## Triple dot is not handled.
+  ##   Triple dot is not handled.
   ##
   ## See also:
   ## * `absolutePath proc <#absolutePath,string>`_
@@ -1722,9 +1722,8 @@ proc createSymlink*(src, dest: string) {.noWeirdTarget.} =
   ## Create a symbolic link at `dest` which points to the item specified
   ## by `src`. On most operating systems, will fail if a link already exists.
   ##
-  ## **Warning**:
+  ## .. warning:: Some OS's (such as Microsoft Windows) restrict the creation
-  ## Some OS's (such as Microsoft Windows) restrict the creation
+  ##   of symlinks to root users (administrators) or users with developper mode enabled.
-  ## of symlinks to root users (administrators) or users with developper mode enabled.
   ##
   ## See also:
   ## * `createHardlink proc <#createHardlink,string,string>`_
@@ -2349,9 +2348,8 @@ iterator walkDirRec*(dir: string,
   ## If ``relative`` is true (default: false) the resulting path is
   ## shortened to be relative to ``dir``, otherwise the full path is returned.
   ##
-  ## **Warning**:
+  ## .. warning:: Modifying the directory structure while the iterator
-  ## Modifying the directory structure while the iterator
+  ##   is traversing may result in undefined behavior!
-  ## is traversing may result in undefined behavior!
   ##
   ## Walking is recursive. `followFilter` controls the behaviour of the iterator:
   ##
@@ -2584,8 +2582,8 @@ proc createHardlink*(src, dest: string) {.noWeirdTarget.} =
   ## Create a hard link at `dest` which points to the item specified
   ## by `src`.
   ##
-  ## **Warning**: Some OS's restrict the creation of hard links to
+  ## .. warning:: Some OS's restrict the creation of hard links to
-  ## root users (administrators).
+  ##   root users (administrators).
   ##
   ## See also:
   ## * `createSymlink proc <#createSymlink,string,string>`_

lib/pure/osproc.nim

@@ -80,9 +80,8 @@ proc execProcess*(command: string, workingDir: string = "",
   ## A convenience procedure that executes ``command`` with ``startProcess``
   ## and returns its output as a string.
   ##
-  ## **WARNING:** This function uses `poEvalCommand` by default for backwards
+  ## .. warning:: This function uses `poEvalCommand` by default for backwards
-  ## compatibility.
+  ##   compatibility. Make sure to pass options explicitly.
-  ## Make sure to pass options explicitly.
   ##
   ## See also:
   ## * `startProcess proc
@@ -155,9 +154,9 @@ proc startProcess*(command: string, workingDir: string = "",
 proc close*(p: Process) {.rtl, extern: "nosp$1", tags: [WriteIOEffect].}
   ## When the process has finished executing, cleanup related handles.
   ##
-  ## **WARNING:** If the process has not finished executing, this will forcibly
+  ## .. warning:: If the process has not finished executing, this will forcibly
-  ## terminate the process. Doing so may result in zombie processes and
+  ##   terminate the process. Doing so may result in zombie processes and
-  ## `pty leaks <http://stackoverflow.com/questions/27021641/how-to-fix-request-failed-on-channel-0>`_.
+  ##   `pty leaks <http://stackoverflow.com/questions/27021641/how-to-fix-request-failed-on-channel-0>`_.
 
 proc suspend*(p: Process) {.rtl, extern: "nosp$1", tags: [].}
   ## Suspends the process `p`.
@@ -215,8 +214,8 @@ proc waitForExit*(p: Process, timeout: int = -1): int {.rtl,
     extern: "nosp$1", tags: [].}
   ## Waits for the process to finish and returns `p`'s error code.
   ##
-  ## **WARNING**: Be careful when using `waitForExit` for processes created without
+  ## .. warning:: Be careful when using `waitForExit` for processes created without
-  ## `poParentStreams` because they may fill output buffers, causing deadlock.
+  ##   `poParentStreams` because they may fill output buffers, causing deadlock.
   ##
   ## On posix, if the process has exited because of a signal, 128 + signal
   ## number will be returned.
@@ -230,8 +229,8 @@ proc peekExitCode*(p: Process): int {.rtl, extern: "nosp$1", tags: [].}
 proc inputStream*(p: Process): Stream {.rtl, extern: "nosp$1", tags: [].}
   ## Returns ``p``'s input stream for writing to.
   ##
-  ## **WARNING**: The returned `Stream` should not be closed manually as it
+  ## .. warning:: The returned `Stream` should not be closed manually as it
-  ## is closed when closing the Process ``p``.
+  ##   is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `outputStream proc <#outputStream,Process>`_
@@ -244,8 +243,8 @@ proc outputStream*(p: Process): Stream {.rtl, extern: "nosp$1", tags: [].}
   ## Use `peekableOutputStream proc <#peekableOutputStream,Process>`_
   ## if you need to peek stream.
   ##
-  ## **WARNING**: The returned `Stream` should not be closed manually as it
+  ## .. warning:: The returned `Stream` should not be closed manually as it
-  ## is closed when closing the Process ``p``.
+  ##   is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `inputStream proc <#inputStream,Process>`_
@@ -258,8 +257,8 @@ proc errorStream*(p: Process): Stream {.rtl, extern: "nosp$1", tags: [].}
   ## Use `peekableErrorStream proc <#peekableErrorStream,Process>`_
   ## if you need to peek stream.
   ##
-  ## **WARNING**: The returned `Stream` should not be closed manually as it
+  ## .. warning:: The returned `Stream` should not be closed manually as it
-  ## is closed when closing the Process ``p``.
+  ##   is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `inputStream proc <#inputStream,Process>`_
@@ -270,8 +269,8 @@ proc peekableOutputStream*(p: Process): Stream {.rtl, extern: "nosp$1", tags: []
   ##
   ## You can peek returned stream.
   ##
-  ## **WARNING**: The returned `Stream` should not be closed manually as it
+  ## .. warning:: The returned `Stream` should not be closed manually as it
-  ## is closed when closing the Process ``p``.
+  ##   is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `outputStream proc <#outputStream,Process>`_
@@ -282,8 +281,8 @@ proc peekableErrorStream*(p: Process): Stream {.rtl, extern: "nosp$1", tags: [],
   ##
   ## You can run peek operation to returned stream.
   ##
-  ## **WARNING**: The returned `Stream` should not be closed manually as it
+  ## .. warning:: The returned `Stream` should not be closed manually as it
-  ## is closed when closing the Process ``p``.
+  ##   is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `errorStream proc <#errorStream,Process>`_
@@ -293,8 +292,8 @@ proc inputHandle*(p: Process): FileHandle {.rtl, extern: "nosp$1",
   tags: [].} =
   ## Returns ``p``'s input file handle for writing to.
   ##
-  ## **WARNING**: The returned `FileHandle` should not be closed manually as
+  ## .. warning:: The returned `FileHandle` should not be closed manually as
-  ## it is closed when closing the Process ``p``.
+  ##   it is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `outputHandle proc <#outputHandle,Process>`_
@@ -305,8 +304,8 @@ proc outputHandle*(p: Process): FileHandle {.rtl, extern: "nosp$1",
     tags: [].} =
   ## Returns ``p``'s output file handle for reading from.
   ##
-  ## **WARNING**: The returned `FileHandle` should not be closed manually as
+  ## .. warning:: The returned `FileHandle` should not be closed manually as
-  ## it is closed when closing the Process ``p``.
+  ##   it is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `inputHandle proc <#inputHandle,Process>`_
@@ -317,8 +316,8 @@ proc errorHandle*(p: Process): FileHandle {.rtl, extern: "nosp$1",
     tags: [].} =
   ## Returns ``p``'s error file handle for reading from.
   ##
-  ## **WARNING**: The returned `FileHandle` should not be closed manually as
+  ## .. warning:: The returned `FileHandle` should not be closed manually as
-  ## it is closed when closing the Process ``p``.
+  ##   it is closed when closing the Process ``p``.
   ##
   ## See also:
   ## * `inputHandle proc <#inputHandle,Process>`_

lib/pure/terminal.nim

@@ -332,7 +332,7 @@ when defined(windows):
   proc setCursorYPos*(f: File, y: int) =
     ## Sets the terminal's cursor to the y position.
     ## The x position is not changed.
-    ## **Warning**: This is not supported on UNIX!
+    ## .. warning:: This is not supported on UNIX!
     when defined(windows):
       let h = conHandle(f)
       var scrbuf: CONSOLE_SCREEN_BUFFER_INFO

lib/std/jsfetch.nim

@@ -84,7 +84,7 @@ when defined(nimExperimentalJsfetch) or defined(nimdoc):
   proc unsafeNewFetchOptions*(metod, body, mode, credentials, cache, referrerPolicy: cstring;
       keepalive: bool; redirect = "follow".cstring; referrer = "client".cstring; integrity = "".cstring): FetchOptions {.importjs:
       "{method: #, body: #, mode: #, credentials: #, cache: #, referrerPolicy: #, keepalive: #, redirect: #, referrer: #, integrity: #}".}
-    ## .. Warning:: Unsafe `newfetchOptions`.
+    ## .. warning:: Unsafe `newfetchOptions`.
 
   func newfetchOptions*(metod: HttpMethod; body: cstring;
       mode: FetchModes; credentials: FetchCredentials; cache: FetchCaches; referrerPolicy: FetchReferrerPolicies;

lib/std/jsformdata.nim

@@ -17,7 +17,7 @@ func add*(self: FormData; name: cstring; value: SomeNumber | bool | cstring, fil
 func delete*(self: FormData; name: cstring) {.importjs: "#.$1(#)".}
   ## https://developer.mozilla.org/en-US/docs/Web/API/FormData/delete
   ##
-  ## .. Warning:: Deletes *all items* with the same key name.
+  ## .. warning:: Deletes *all items* with the same key name.
 
 func getAll*(self: FormData; name: cstring): seq[cstring] {.importjs: "#.$1(#)".}
   ## https://developer.mozilla.org/en-US/docs/Web/API/FormData/getAll

lib/std/jsheaders.nim

@@ -14,7 +14,7 @@ func add*(self: Headers; key: cstring; value: cstring) {.importjs: "#.append(#,
 func delete*(self: Headers; key: cstring) {.importjs: "#.$1(#)".}
   ## https://developer.mozilla.org/en-US/docs/Web/API/Headers/delete
   ##
-  ## .. Warning:: Delete *all* items with `key` from the headers, including duplicated keys.
+  ## .. warning:: Delete *all* items with `key` from the headers, including duplicated keys.
 
 func hasKey*(self: Headers; key: cstring): bool {.importjs: "#.has(#)".}
   ## https://developer.mozilla.org/en-US/docs/Web/API/Headers/has

lib/system/iterators.nim

@@ -271,9 +271,9 @@ 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.
+  ## .. warning:: This really transforms the 'for' and unrolls the loop.
-  ## The current implementation also has a bug
+  ##   The current implementation also has a bug
-  ## that affects symbol binding in the loop body.
+  ##   that affects symbol binding in the loop body.
   runnableExamples:
     var t = (1, "foo")
     for v in fields(t): v = default(typeof(v))
@@ -283,9 +283,9 @@ iterator fields*[S:tuple|object, T:tuple|object](x: S, y: T): tuple[key: string,
   magic: "Fields", noSideEffect.} =
   ## Iterates over every field of `x` and `y`.
   ##
-  ## **Warning**: This really transforms the 'for' and unrolls the loop.
+  ## .. warning:: This really transforms the 'for' and unrolls the loop.
-  ## The current implementation also has a bug that affects symbol binding
+  ##   The current implementation also has a bug that affects symbol binding
-  ## in the loop body.
+  ##   in the loop body.
   runnableExamples:
     var t1 = (1, "foo")
     var t2 = default(typeof(t1))
@@ -304,9 +304,9 @@ iterator fieldPairs*[T: tuple|object](x: T): tuple[key: string, val: 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
+  ##   current implementation also has a bug that affects symbol binding in the
-  ## loop body.
+  ##   loop body.
   runnableExamples:
     type
       Custom = object
@@ -325,9 +325,9 @@ iterator fieldPairs*[S: tuple|object, T: tuple|object](x: S, y: T): tuple[
   magic: "FieldPairs", noSideEffect.} =
   ## Iterates over every field of `x` and `y`.
   ##
-  ## **Warning**: This really transforms the 'for' and unrolls the loop.
+  ## .. warning:: This really transforms the 'for' and unrolls the loop.
-  ## The current implementation also has a bug that affects symbol binding
+  ##   The current implementation also has a bug that affects symbol binding
-  ## in the loop body.
+  ##   in the loop body.
   runnableExamples:
     type Foo = object
       x1: int