chore: reduce walls of comments

Author: gmelodie

examples/echo/echo.nim

@@ -6,9 +6,7 @@ import ffi, chronos, strutils
 type Echo = object
   prefix: string
 
-# `-d:ffiEchoAbiC` builds the `abi = c` variant (`_CWire` structs on the wire);
-# the default is the CBOR ABI. The same source drives both the `c_bindings/`
-# (CBOR) and `c_abi_bindings/` example outputs.
+# `-d:ffiEchoAbiC` builds the `abi = c` variant; default is the CBOR ABI.
 when defined(ffiEchoAbiC):
   declareLibrary("echo", Echo, defaultABIFormat = "c")
 else:

examples/timer/timer.nim

@@ -2,17 +2,11 @@ import ffi, chronos, options
 
 type Maybe[T] = Option[T]
 
-# The library's main state type. The FFI context owns one instance.
-# Named `MyTimer` (not `Timer`) so the C-exported symbols are
-# `my_timer_create` / `my_timer_destroy` / ... — `timer_create` would
-# collide with POSIX `<time.h>`'s `int timer_create(clockid_t, ...)` which
-# `<pthread.h>` transitively drags in on Linux.
+# Named `MyTimer` (not `Timer`) so C symbols like `my_timer_create` don't collide with POSIX `<time.h>`'s `timer_create`.
 type MyTimer = object
   name: string # set at creation time, read back in each response
 
-# `defaultABIFormat` selects the wire format every {.ffi.} / {.ffiEvent.} / ...
-# in this library inherits; "cbor" is the default and can be overridden per
-# annotation with an `"abi = ..."` spec.
+# `defaultABIFormat` is the wire format every annotation inherits (override per-annotation with "abi = ...").
 declareLibrary("my_timer", MyTimer, defaultABIFormat = "cbor")
 
 type TimerConfig {.ffi.} = object
@@ -37,37 +31,27 @@ type ComplexResponse {.ffi.} = object
   itemCount: int
   hasNote: bool
 
-# --- Library-initiated event ----------------------------------------------
-# Demonstrates the {.ffiEvent.} macro: a typed event the library can fire
-# from any {.ffi.} handler, dispatched to the foreign side's registered
-# callback as CBOR. Per-target codegens emit a typed handler-struct +
-# dispatcher so the foreign caller decodes nothing by hand.
+# {.ffiEvent.}: a typed event any {.ffi.} handler can fire to the foreign callback.
 type EchoEvent {.ffi.} = object
   message: string
   echoCount: int
 
 proc onEchoFired*(evt: EchoEvent) {.ffiEvent: "on_echo_fired".}
 
-# --- Constructor -----------------------------------------------------------
-# Called once from Rust. Creates the FFIContext + MyTimer.
-# Uses chronos (await sleepAsync) so the body is async.
+# Constructor: creates the FFIContext + MyTimer; async via chronos.
 proc myTimerCreate*(config: TimerConfig): Future[Result[MyTimer, string]] {.ffiCtor.} =
   await sleepAsync(1.milliseconds) # proves chronos is live on the FFI thread
   return ok(MyTimer(name: config.name))
 
-# --- Async method ----------------------------------------------------------
-# Waits `delayMs` milliseconds (non-blocking, on the chronos event loop)
-# then echoes the message back with a request counter.
+# Async method: sleeps `delayMs` then echoes the message back.
 proc myTimerEcho*(
     timer: MyTimer, req: EchoRequest
 ): Future[Result[EchoResponse, string]] {.ffi.} =
   await sleepAsync(req.delayMs.milliseconds)
   onEchoFired(EchoEvent(message: req.message, echoCount: 1))
   return ok(EchoResponse(echoed: req.message, timerName: timer.name))
 
-# --- Sync method -----------------------------------------------------------
-# No await — the macro detects this and fires the callback inline,
-# without going through the request channel.
+# Sync method: no await, so the macro fires the callback inline.
 proc myTimerVersion*(timer: MyTimer): Future[Result[string, string]] {.ffi.} =
   return ok("nim-timer v0.1.0")
 
@@ -82,12 +66,7 @@ proc myTimerComplex*(
   return
     ok(ComplexResponse(summary: summary, itemCount: count, hasNote: req.note.isSome))
 
-# --- Multiple complex parameters -------------------------------------------
-# Demonstrates how a {.ffi.} proc handles several object-typed parameters at
-# once. Each parameter is its own {.ffi.} type, so it lands in the generated
-# foreign-side bindings as a first-class struct/class, and the per-proc Req
-# envelope (MyTimerScheduleReq on the wire) carries all three under field
-# names that match the Nim params.
+# Multiple object-typed params: each is its own {.ffi.} type, all carried in one per-proc Req envelope.
 type JobSpec {.ffi.} = object
   name: string
   payload: seq[string]
@@ -112,10 +91,7 @@ type ScheduleResult {.ffi.} = object
 proc myTimerSchedule*(
     timer: MyTimer, job: JobSpec, retry: RetryPolicy, schedule: ScheduleConfig
 ): Future[Result[ScheduleResult, string]] {.ffi.} =
-  ## Composes three independent object-typed parameters (`job`, `retry`,
-  ## `schedule`) into a single scheduling decision. The macro packs them into
-  ## one CBOR-encoded request envelope on the wire and unpacks them back into
-  ## the named locals before this body runs.
+  ## Three object-typed params (`job`, `retry`, `schedule`) packed into one CBOR envelope.
   await sleepAsync(1.milliseconds)
   if job.name.len == 0:
     return err("job name must not be empty")
@@ -137,22 +113,8 @@ proc myTimerSchedule*(
   )
 
 proc my_timer_destroy*(timer: MyTimer) {.ffiDtor.} =
-  ## Tears down the FFI context created by my_timer_create.
-  ## Blocks until the FFI thread and watchdog thread have joined.
+  ## Tears down the FFI context; blocks until FFI + watchdog threads join.
   discard
 
-# genBindings() must be the LAST top-level call in the FFI root file —
-# after every {.ffi.}, {.ffiCtor.} and {.ffiDtor.} pragma. Each pragma
-# fires at compile time and registers its proc into the compile-time
-# ffiProcRegistry / ffiTypeRegistry; genBindings() then reads those
-# registries to emit the language bindings. If genBindings() runs before
-# a pragma, that proc is silently absent from the generated bindings.
-#
-# Multi-file libraries: keep all .ffi./.ffiCtor./.ffiDtor. pragmas in
-# imported sub-modules and call genBindings() once at the bottom of the
-# top-level file that imports them — Nim resolves imports before the
-# importing file's body runs, so the registries are fully populated by
-# the time genBindings() executes.
-#
-# genBindings() is a compile-time no-op unless -d:ffiGenBindings is set.
+# genBindings() must be the LAST top-level call, after every pragma has registered its proc; it reads those registries to emit bindings (no-op unless -d:ffiGenBindings).
 genBindings()

ffi/alloc.nim

@@ -1,24 +1,13 @@
 ## Cross-thread allocation helpers backed by libc `malloc`/`free`.
-##
-## We deliberately avoid Nim's `allocShared`/`deallocShared` here. Under
-## `--mm:orc` they delegate to the per-thread `allocator` MemRegion stored
-## in TLS; freeing such a buffer from a different thread later walks
-## `chunk.owner` back to that MemRegion. If the original thread has exited
-## by then (e.g. a `std::async` worker that produced the FFI request and
-## was destroyed before the FFI thread ran `deleteRequest`), `chunk.owner`
-## dangles into reclaimed TLS and `addToSharedFreeList` segfaults — TSan on
-## ARM reproduces this from `TimerE2E.ThreadedHammer`. `malloc`/`free` are
-## process-global and thread-lifetime-independent, so freeing on a different
-## thread is safe.
+## Avoids Nim `allocShared` whose TLS-owned MemRegion segfaults when freed from a
+## thread other than the one that allocated (and may have since exited); libc is process-global.
 
 import system/ansi_c
 
-## Can be shared safely between threads
 type SharedSeq*[T] = tuple[data: ptr UncheckedArray[T], len: int]
 
 proc alloc*(str: cstring): cstring =
-  ## Allocates a fresh null-terminated copy of `str` via `c_malloc`. The
-  ## returned pointer must be released with `dealloc(cstring)`.
+  ## Fresh null-terminated `c_malloc` copy of `str`; free with `dealloc(cstring)`.
   if str.isNil():
     var ret = cast[cstring](c_malloc(1))
     ret[0] = '\0'
@@ -29,8 +18,6 @@ proc alloc*(str: cstring): cstring =
   return ret
 
 proc alloc*(str: string): cstring =
-  ## Allocates a fresh null-terminated copy of `str` via `c_malloc`. The
-  ## returned pointer must be released with `dealloc(cstring)`.
   var ret = cast[cstring](c_malloc(csize_t(str.len + 1)))
   let s = cast[seq[char]](str)
   for i in 0 ..< str.len:
@@ -39,20 +26,15 @@ proc alloc*(str: string): cstring =
   return ret
 
 proc dealloc*(p: cstring) {.inline.} =
-  ## Frees a buffer obtained from one of the `alloc(...)` overloads above.
-  ## Nil-safe.
+  ## Frees an `alloc(...)` buffer. Nil-safe.
   if not p.isNil():
     c_free(cast[pointer](p))
 
 proc allocBox*(size: int): pointer =
-  ## `c_malloc` block for a cross-thread callback box (allocated on the foreign
-  ## caller thread, freed on the FFI thread). Uses libc for the same
-  ## thread-lifetime safety reason as the rest of this module. Free with
-  ## `freeBox`.
+  ## `c_malloc` block for a cross-thread callback box; free with `freeBox`.
   c_malloc(csize_t(size))
 
 proc freeBox*(p: pointer) =
-  ## Releases a block from `allocBox`. Nil-safe.
   if not p.isNil():
     c_free(p)
 
@@ -70,8 +52,6 @@ proc deallocSharedSeq*[T](s: var SharedSeq[T]) =
   s.len = 0
 
 proc toSeq*[T](s: SharedSeq[T]): seq[T] =
-  ## Creates a seq[T] from a SharedSeq[T]. No explicit dealloc is required
-  ## as req[T] is a GC managed type.
   var ret = newSeq[T]()
   for i in 0 ..< s.len:
     ret.add(s.data[i])

ffi/cbor_serial.nim

@@ -1,52 +1,21 @@
-## Thin wrapper around `cbor_serialization` (vacp2p/nim-cbor-serialization) that
-## adapts the library's exception-based API to the `Result[T, string]` shape the
-## FFI plumbing expects, and adds the few transport-only details the FFI layer
-## needs on top:
-##
-##   - `cborEncodeShared` writes into a `c_malloc` buffer so the FFI thread
-##     can take ownership of the bytes without a second copy. `c_malloc`
-##     (not `allocShared`) because the buffer must be freeable from the FFI
-##     thread after the producing thread may have exited — see the note in
-##     `ffi/ffi_thread_request.nim`.
-##   - `CborNullByte` is the canonical "successful but no value" wire sentinel.
-##
-## `cborEncode` / `cborDecode` are the public API the macros and tests use.
-##
-## Type contract for `.ffi.` payloads:
-##
-##   - Plain `object` types flow as value copies — fields are serialized and
-##     the foreign side reconstructs an independent value.
-##   - `ref T` is *also* a value copy: `cbor_serialization`'s default `ref T`
-##     writer dereferences and encodes the pointee, so the receiving side
-##     allocates a fresh `ref` local to its own GC heap. No object identity
-##     is preserved across the boundary — the two sides own independent
-##     copies after decode.
-##   - Raw `pointer` / `ptr T` are rejected at macro-expansion time (see
-##     `rejectRawPtrType` in `internal/ffi_macro.nim`). The only address that
-##     legitimately crosses the boundary is the opaque ctx handle returned by
-##     `.ffiCtor.`, which is validated against `FFIContextPool` on every
-##     re-entry. Arbitrary user pointers would lack that validation.
+## `cbor_serialization` wrapper adapting its exception API to `Result[T, string]` for the FFI layer.
+## `.ffi.` payloads (plain `object` and `ref T`) cross as value copies; raw `pointer`/`ptr T` are
+## rejected at macro-expansion time (see `rejectRawPtrType`).
 
 import system/ansi_c
 import cbor_serialization, cbor_serialization/std/options, results
 
 export cbor_serialization, options, results
 
 const CborNullByte*: byte = 0xf6'u8
-  ## CBOR encoding of `null` — used as the wire sentinel for empty OK payloads.
+  ## CBOR `null` — wire sentinel for empty OK payloads.
 
 proc cborEncode*[T](x: T): seq[byte] =
-  ## CBOR-encode any cbor_serialization-supported type (plus `pointer` / `ptr T`
-  ## via our custom writers) into a fresh `seq[byte]`.
   return Cbor.encode(x)
 
 proc cborEncodeShared*[T](x: T): tuple[data: ptr UncheckedArray[byte], len: int] =
-  ## Encodes `x` into a `c_malloc` buffer.
-  ##
-  ## The returned `data` is owned by the caller and must be freed exactly
-  ## once via `cborFreeShared`. The
-  ## `FFIThreadRequest deleteRequest` path frees adopted buffers
-  ## automatically. Empty payloads return `(nil, 0)` without allocating.
+  ## Encodes `x` into a caller-owned `c_malloc` buffer (free via `cborFreeShared`).
+  ## Empty payloads return `(nil, 0)` without allocating.
   let bytes = Cbor.encode(x)
   if bytes.len == 0:
     return (nil, 0)
@@ -55,16 +24,13 @@ proc cborEncodeShared*[T](x: T): tuple[data: ptr UncheckedArray[byte], len: int]
   return (buf, bytes.len)
 
 proc cborFreeShared*(data: var ptr UncheckedArray[byte]) =
-  ## Releases a buffer previously returned by `cborEncodeShared` and nils
-  ## the caller's pointer so a stale reference can't be reused after free.
-  ## Safe to call with `nil` (the `(nil, 0)` empty-payload contract).
+  ## Frees a `cborEncodeShared` buffer and nils the pointer. Nil-safe.
   if not data.isNil():
     c_free(data)
     data = nil
 
 proc cborDecode*[T](data: openArray[byte], _: typedesc[T]): Result[T, string] =
-  ## Decode `data` into a `T`, converting any cbor_serialization exception
-  ## into a `Result.err` carrying the exception message.
+  ## Decode `data` into a `T`, mapping any exception to `Result.err`.
   try:
     let v = Cbor.decode(data, T)
     return ok(v)
@@ -74,8 +40,7 @@ proc cborDecode*[T](data: openArray[byte], _: typedesc[T]): Result[T, string] =
 proc cborDecodePtr*[T](
     data: ptr UncheckedArray[byte], dataLen: int, _: typedesc[T]
 ): Result[T, string] =
-  ## Convenience for ptr+len buffers (used by the macro to avoid binding an
-  ## openArray to a `let`).
+  ## Convenience for ptr+len buffers.
   if dataLen <= 0:
     return cborDecode(default(seq[byte]), T)
   cborDecode(toOpenArray(data, 0, dataLen - 1), T)