doc generation fixes (#464)

* doc generation fixes

* fix

.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

.gitignore

@@ -4,3 +4,4 @@ nimble.develop
 nimble.paths
 /build/
 nimbledeps
+/docs

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

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()

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

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":
+  when chronosEventEngine == "epoll":
     include ./ioselects/ioselectors_epoll
-elif chronosEventEngine == "kqueue":
+  elif chronosEventEngine == "kqueue":
     include ./ioselects/ioselectors_kqueue
-elif chronosEventEngine == "poll":
+  elif chronosEventEngine == "poll":
     include ./ioselects/ioselectors_poll
-else:
+  else:
     {.fatal: "Event engine `" & chronosEventEngine & "` is not supported!".}

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()