mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-04-19 05:50:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Use .. warning:: (#17320)

Browse Source
This commit is contained in:
konsumlamm
2021-03-10 19:39:23 +01:00
committed by GitHub
parent eb07a5a75b
commit 9819fb21d8
15 changed files with 84 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
lib/posix/posix.nim
View File

@@ -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.}

2
lib/pure/asyncdispatch.nim
View File

@@ -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")

4
lib/pure/collections/tables.nim
View File

@@ -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
@@ -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]>`_

2
lib/pure/dynlib.nim
View File

@@ -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:

9
lib/pure/includes/oserr.nim
View File

@@ -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>`_

18
lib/pure/logging.nim
View File

@@ -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.
@@ -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>`_
@@ -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>`_

6
lib/pure/nativesockets.nim
View File

@@ -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")
@@ -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)
@@ -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),

16
lib/pure/net.nim
View File

@@ -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,
## 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,

24
lib/pure/os.nim
View File

@@ -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:
@@ -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>`_
@@ -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>`_
@@ -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.
##
@@ -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:
##
@@ -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>`_
@@ -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,

47
lib/pure/osproc.nim
View File

@@ -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
@@ -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`.
@@ -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.
@@ -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>`_
@@ -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>`_
@@ -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>`_
@@ -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>`_
@@ -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>`_
@@ -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>`_
@@ -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>`_
@@ -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>`_

2
lib/pure/terminal.nim
View File

@@ -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

2
lib/std/jsfetch.nim
View File

@@ -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;

2
lib/std/jsformdata.nim
View File

@@ -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

2
lib/std/jsheaders.nim
View File

@@ -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

24
lib/system/iterators.nim
View File

@@ -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.
## The current implementation also has a bug
## that affects symbol binding in the loop body.
## .. 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.
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.
## The current implementation also has a bug that affects symbol binding
## in the loop body.
## .. 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.
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
## current implementation also has a bug that affects symbol binding in the
## loop body.
## .. 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.
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.
## The current implementation also has a bug that affects symbol binding
## in the loop body.
## .. 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.
runnableExamples:
type Foo = object
x1: int