Skip to content

Commit

Permalink
Use .. warning:: (nim-lang#17320)
Browse files Browse the repository at this point in the history
  • Loading branch information
konsumlamm authored and ardek66 committed Mar 26, 2021
1 parent 6e1766b commit 52fdac9
Show file tree
Hide file tree
Showing 15 changed files with 84 additions and 88 deletions.
12 changes: 6 additions & 6 deletions lib/posix/posix.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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
## can't be a string literal. If in doubt make a copy of the cstring before
## passing it in.
## .. 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
## 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
## can't be a string literal. If in doubt make a copy of the cstring before
## passing it in.
## .. 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
## passing it in.

proc mkdtemp*(tmpl: cstring): pointer {.importc, header: "<stdlib.h>", sideEffect.}

Expand Down
2 changes: 1 addition & 1 deletion lib/pure/asyncdispatch.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down
4 changes: 2 additions & 2 deletions lib/pure/collections/tables.nim
Original file line number Diff line number Diff line change
Expand Up @@ -598,7 +598,7 @@ template withValue*[A, B](t: var Table[A, B], key: A, value, body: untyped) =
# block is executed only if `key` in `t`
value.name = "Nim"
value.uid = 1314

t.withValue(2, value) do:
value.name = "No"
value.uid = 521
Expand Down Expand Up @@ -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]>`_
Expand Down
2 changes: 1 addition & 1 deletion lib/pure/dynlib.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
9 changes: 4 additions & 5 deletions lib/pure/includes/oserr.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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**:
## 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
## 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.
## .. warning:: 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
## 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.
##
## See also:
## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
Expand Down
18 changes: 9 additions & 9 deletions lib/pure/logging.nim
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@
## ``levelThreshold`` field and the global log filter. The latter can be changed
## with the `setLogFilter proc<#setLogFilter,Level>`_.
##
## **Warning:**
## * For loggers that log to a console or to files, only error and fatal
## .. warning::
## 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.
Expand Down Expand Up @@ -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
## handler will be used in multiple threads, this proc should be called in
## each of those threads.
## .. 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
## each of those threads.
##
## See also:
## * `getHandlers proc<#getHandlers>`_
Expand All @@ -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
## 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
## logging levels.
## .. 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
## thread unless it is intended that different threads should log at different
## logging levels.
##
## See also:
## * `getLogFilter proc<#getLogFilter>`_
Expand Down
6 changes: 3 additions & 3 deletions lib/pure/nativesockets.nim
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ proc getProtoByName*(name: string): int {.since: (1, 3, 5).} =
let protoent = winlean.getprotobyname(name.cstring)
else:
let protoent = posix.getprotobyname(name.cstring)

if protoent == nil:
raise newException(OSError, "protocol not found")

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -492,7 +492,7 @@ proc getAddrString*(sockAddr: ptr SockAddr): string =
proc getAddrString*(sockAddr: ptr SockAddr, strAddress: var string) =
## Stores in `strAddress` the string representation of the address inside
## `sockAddr`
##
##
## **Note**
## * `strAddress` must be initialized to 46 in length.
assert(46 == len(strAddress),
Expand Down
16 changes: 8 additions & 8 deletions lib/pure/net.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)

Expand All @@ -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,
## so when `socket` is buffered the non-buffered implementation will be
## used. Therefore if `socket` contains something in its buffer this
## function will make no effort to return it.
## .. warning:: This function does not yet have a buffered implementation,
## so when `socket` is buffered the non-buffered implementation will be
## used. Therefore if `socket` contains something in its buffer this
## 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,
Expand Down
24 changes: 11 additions & 13 deletions lib/pure/os.nim
Original file line number Diff line number Diff line change
Expand Up @@ -961,7 +961,7 @@ proc getTempDir*(): string {.rtl, extern: "nos$1",
##
## You can override this implementation
## by adding `-d:tempDir=mytempname` to your compiler invocation.
##
##
## **Note:** This proc does not check whether the returned path exists.
##
## See also:
Expand Down Expand Up @@ -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.
## Triple dot is not handled.
## .. warning:: URL-encoded and Unicode attempts at directory traversal are not detected.
## Triple dot is not handled.
##
## See also:
## * `absolutePath proc <#absolutePath,string>`_
Expand Down Expand Up @@ -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**:
## Some OS's (such as Microsoft Windows) restrict the creation
## of symlinks to root users (administrators) or users with developper mode enabled.
## .. warning:: Some OS's (such as Microsoft Windows) restrict the creation
## of symlinks to root users (administrators) or users with developper mode enabled.
##
## See also:
## * `createHardlink proc <#createHardlink,string,string>`_
Expand Down Expand Up @@ -1815,7 +1814,7 @@ proc copyFile*(source, dest: string, options = {cfSymlinkFollow}) {.rtl,
##
## If `dest` already exists, the file attributes
## will be preserved and the content overwritten.
##
##
## On OSX, `copyfile` C api will be used (available since OSX 10.5) unless
## `-d:nimLegacyCopyFile` is used.
##
Expand Down Expand Up @@ -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**:
## Modifying the directory structure while the iterator
## is traversing may result in undefined behavior!
## .. warning:: Modifying the directory structure while the iterator
## is traversing may result in undefined behavior!
##
## Walking is recursive. `followFilter` controls the behaviour of the iterator:
##
Expand Down Expand Up @@ -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
## root users (administrators).
## .. warning:: Some OS's restrict the creation of hard links to
## root users (administrators).
##
## See also:
## * `createSymlink proc <#createSymlink,string,string>`_
Expand Down Expand Up @@ -2838,7 +2836,7 @@ when defined(nimdoc):
##
## `i` should be in the range `1..paramCount()`, the `IndexDefect`
## exception will be raised for invalid values. Instead of iterating
## over `paramCount() <#paramCount>`_ with this proc you can
## over `paramCount() <#paramCount>`_ with this proc you can
## call the convenience `commandLineParams() <#commandLineParams>`_.
##
## Similarly to `argv`:idx: in C,
Expand Down
47 changes: 23 additions & 24 deletions lib/pure/osproc.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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
## compatibility.
## Make sure to pass options explicitly.
## .. warning:: This function uses `poEvalCommand` by default for backwards
## compatibility. Make sure to pass options explicitly.
##
## See also:
## * `startProcess proc
Expand Down Expand Up @@ -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
## 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>`_.
## .. warning:: If the process has not finished executing, this will forcibly
## 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>`_.

proc suspend*(p: Process) {.rtl, extern: "nosp$1", tags: [].}
## Suspends the process `p`.
Expand Down Expand Up @@ -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
## `poParentStreams` because they may fill output buffers, causing deadlock.
## .. warning:: Be careful when using `waitForExit` for processes created without
## `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.
Expand All @@ -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
## is closed when closing the Process ``p``.
## .. warning:: The returned `Stream` should not be closed manually as it
## is closed when closing the Process ``p``.
##
## See also:
## * `outputStream proc <#outputStream,Process>`_
Expand All @@ -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
## is closed when closing the Process ``p``.
## .. warning:: The returned `Stream` should not be closed manually as it
## is closed when closing the Process ``p``.
##
## See also:
## * `inputStream proc <#inputStream,Process>`_
Expand All @@ -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
## is closed when closing the Process ``p``.
## .. warning:: The returned `Stream` should not be closed manually as it
## is closed when closing the Process ``p``.
##
## See also:
## * `inputStream proc <#inputStream,Process>`_
Expand All @@ -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
## is closed when closing the Process ``p``.
## .. warning:: The returned `Stream` should not be closed manually as it
## is closed when closing the Process ``p``.
##
## See also:
## * `outputStream proc <#outputStream,Process>`_
Expand All @@ -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
## is closed when closing the Process ``p``.
## .. warning:: The returned `Stream` should not be closed manually as it
## is closed when closing the Process ``p``.
##
## See also:
## * `errorStream proc <#errorStream,Process>`_
Expand All @@ -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
## it is closed when closing the Process ``p``.
## .. warning:: The returned `FileHandle` should not be closed manually as
## it is closed when closing the Process ``p``.
##
## See also:
## * `outputHandle proc <#outputHandle,Process>`_
Expand All @@ -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
## it is closed when closing the Process ``p``.
## .. warning:: The returned `FileHandle` should not be closed manually as
## it is closed when closing the Process ``p``.
##
## See also:
## * `inputHandle proc <#inputHandle,Process>`_
Expand All @@ -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
## it is closed when closing the Process ``p``.
## .. warning:: The returned `FileHandle` should not be closed manually as
## it is closed when closing the Process ``p``.
##
## See also:
## * `inputHandle proc <#inputHandle,Process>`_
Expand Down
2 changes: 1 addition & 1 deletion lib/pure/terminal.nim
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 52fdac9

Please sign in to comment.