From 9759f01016c5d6b511c6eae3bf8376cc456fc0de Mon Sep 17 00:00:00 2001 From: Jacek Sieka Date: Wed, 8 Nov 2023 21:20:24 +0100 Subject: [PATCH] doc generation fixes (#464) * doc generation fixes * fix --- .github/workflows/doc.yml | 6 ++--- .gitignore | 1 + chronos/config.nim | 4 ++- chronos/internal/asyncengine.nim | 42 +++++++++++++++++++++++++------- chronos/osdefs.nim | 2 ++ chronos/selectors2.nim | 17 ++++++------- chronos/transports/common.nim | 2 +- 7 files changed, 51 insertions(+), 23 deletions(-) diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 1668eb0..6e1510a 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -15,13 +15,13 @@ jobs: continue-on-error: true steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: submodules: true - uses: jiro4989/setup-nim-action@v1 with: - nim-version: '1.6.6' + nim-version: '1.6.16' - name: Generate doc run: | @@ -35,7 +35,7 @@ jobs: ls docs - name: Clone the gh-pages branch - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: status-im/nim-chronos ref: gh-pages diff --git a/.gitignore b/.gitignore index c631551..b599536 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ nimble.develop nimble.paths /build/ nimbledeps +/docs diff --git a/chronos/config.nim b/chronos/config.nim index 6af3e31..4055361 100644 --- a/chronos/config.nim +++ b/chronos/config.nim @@ -63,7 +63,9 @@ const ## Initial size of Selector[T]'s array of file descriptors. chronosEventEngine* {.strdefine.}: string = - when defined(linux) and not(defined(android) or defined(emscripten)): + when defined(nimdoc): + "" + elif defined(linux) and not(defined(android) or defined(emscripten)): "epoll" elif defined(macosx) or defined(macos) or defined(ios) or defined(freebsd) or defined(netbsd) or defined(openbsd) or diff --git a/chronos/internal/asyncengine.nim b/chronos/internal/asyncengine.nim index 23d7c6a..0a15799 100644 --- a/chronos/internal/asyncengine.nim +++ b/chronos/internal/asyncengine.nim @@ -169,7 +169,36 @@ func toException*(v: OSErrorCode): ref OSError = newOSError(v) # This helper will allow to use `tryGet()` and raise OSError for # Result[T, OSErrorCode] values. -when defined(windows): +when defined(nimdoc): + type + PDispatcher* = ref object of PDispatcherBase + AsyncFD* = distinct cint + + var gDisp {.threadvar.}: PDispatcher + + proc newDispatcher*(): PDispatcher = discard + proc poll*() = discard + ## Perform single asynchronous step, processing timers and completing + ## tasks. Blocks until at least one event has completed. + ## + ## Exceptions raised during `async` task exection are stored as outcome + ## in the corresponding `Future` - `poll` itself does not raise. + + proc register2*(fd: AsyncFD): Result[void, OSErrorCode] = discard + proc unregister2*(fd: AsyncFD): Result[void, OSErrorCode] = discard + proc addReader2*(fd: AsyncFD, cb: CallbackFunc, + udata: pointer = nil): Result[void, OSErrorCode] = discard + proc removeReader2*(fd: AsyncFD): Result[void, OSErrorCode] = discard + proc addWriter2*(fd: AsyncFD, cb: CallbackFunc, + udata: pointer = nil): Result[void, OSErrorCode] = discard + proc removeWriter2*(fd: AsyncFD): Result[void, OSErrorCode] = discard + proc closeHandle*(fd: AsyncFD, aftercb: CallbackFunc = nil) = discard + proc closeSocket*(fd: AsyncFD, aftercb: CallbackFunc = nil) = discard + proc unregisterAndCloseFd*(fd: AsyncFD): Result[void, OSErrorCode] = discard + + proc `==`*(x: AsyncFD, y: AsyncFD): bool {.borrow, gcsafe.} + +elif defined(windows): {.pragma: stdcallbackFunc, stdcall, gcsafe, raises: [].} export SIGINT, SIGQUIT, SIGTERM @@ -551,12 +580,6 @@ when defined(windows): raise newException(ValueError, osErrorMsg(res.error())) proc poll*() = - ## Perform single asynchronous step, processing timers and completing - ## tasks. Blocks until at least one event has completed. - ## - ## Exceptions raised here indicate that waiting for tasks to be unblocked - ## failed - exceptions from within tasks are instead propagated through - ## their respective futures and not allowed to interrrupt the poll call. let loop = getThreadDispatcher() var curTime = Moment.now() @@ -1241,5 +1264,6 @@ when chronosFutureTracking: ## completed, cancelled or failed). futureList.count -# Perform global per-module initialization. -globalInit() +when not defined(nimdoc): + # Perform global per-module initialization. + globalInit() diff --git a/chronos/osdefs.nim b/chronos/osdefs.nim index ab07721..40a6365 100644 --- a/chronos/osdefs.nim +++ b/chronos/osdefs.nim @@ -1526,6 +1526,8 @@ when defined(posix): INVALID_HANDLE_VALUE* = cint(-1) proc `==`*(x: SocketHandle, y: int): bool = int(x) == y +when defined(nimdoc): + proc `==`*(x: SocketHandle, y: SocketHandle): bool {.borrow.} when defined(macosx) or defined(macos) or defined(bsd): const diff --git a/chronos/selectors2.nim b/chronos/selectors2.nim index c5918fd..5cb8a57 100644 --- a/chronos/selectors2.nim +++ b/chronos/selectors2.nim @@ -36,7 +36,6 @@ import config, osdefs, osutils, oserrno export results, oserrno when defined(nimdoc): - type Selector*[T] = ref object ## An object which holds descriptors to be checked for read/write status @@ -306,11 +305,11 @@ else: doAssert((timeout >= min) and (timeout <= max), "Cannot select with incorrect timeout value, got " & $timeout) -when chronosEventEngine == "epoll": - include ./ioselects/ioselectors_epoll -elif chronosEventEngine == "kqueue": - include ./ioselects/ioselectors_kqueue -elif chronosEventEngine == "poll": - include ./ioselects/ioselectors_poll -else: - {.fatal: "Event engine `" & chronosEventEngine & "` is not supported!".} + when chronosEventEngine == "epoll": + include ./ioselects/ioselectors_epoll + elif chronosEventEngine == "kqueue": + include ./ioselects/ioselectors_kqueue + elif chronosEventEngine == "poll": + include ./ioselects/ioselectors_poll + else: + {.fatal: "Event engine `" & chronosEventEngine & "` is not supported!".} diff --git a/chronos/transports/common.nim b/chronos/transports/common.nim index b7776e5..d8263af 100644 --- a/chronos/transports/common.nim +++ b/chronos/transports/common.nim @@ -199,7 +199,7 @@ proc `$`*(address: TransportAddress): string = "None" proc toHex*(address: TransportAddress): string = - ## Returns hexadecimal representation of ``address`. + ## Returns hexadecimal representation of ``address``. case address.family of AddressFamily.IPv4: "0x" & address.address_v4.toHex()