Add even more documentation

knots/non-blocking.scm

@@ -32,6 +32,16 @@
 
 (define* (non-blocking-open-socket-for-uri uri
                                            #:key (verify-certificate? #t))
+  "Open a socket for URI and return it as a non-blocking port.
+
+For HTTPS URIs the TLS handshake is completed while the socket is
+still blocking (required because Guile's TLS wrapper does not support
+non-blocking handshakes), then the underlying socket is made
+non-blocking.  For plain HTTP the socket is made non-blocking
+immediately.
+
+@code{#:verify-certificate?} controls TLS certificate verification
+and defaults to @code{#t}."
   (define tls-wrap
     (@@ (web client) tls-wrap))
 

knots/parallelism.scm

@@ -267,6 +267,16 @@ invocation of PROC finishes.  REPORT is passed the results for each
                    #:key (parallelism 1)
                    (input-channel (make-channel))
                    (process-channel input-channel))
+  "Convert PROC into a procedure backed by @code{#:parallelism}
+(default: 1) background fibers.  Returns a wrapper that sends its
+arguments to one of the fibers and blocks until the result is
+returned.
+
+@code{#:input-channel} is the channel that callers write requests to;
+defaults to a fresh channel.  @code{#:process-channel} is the channel
+the fibers read from; defaults to @code{#:input-channel}.  Setting
+them differently allows external parties to bypass the wrapper and
+write directly to @code{process-channel}."
   (for-each
    (lambda _
      (spawn-fiber

knots/resource-pool.scm

@@ -1252,6 +1252,10 @@ to the current scheduler.
   pool)
 
 (define (destroy-resource-pool pool)
+  "Destroy POOL, preventing any new checkouts.  Blocks until all
+checked-out resources have been returned, running the pool's
+@code{#:destructor} on each.  Any fibers waiting for a resource
+receive @code{&resource-pool-destroyed}."
   (perform-operation
    (choice-operation
     (wrap-operation
@@ -1468,6 +1472,23 @@ available.  Return the resource once PROC has returned."
     (lambda (resource) exp ...)))
 
 (define* (resource-pool-stats pool #:key (timeout 5))
+  "Return an alist of statistics for POOL with the following keys:
+
+@table @code
+@item resources
+Total number of resources currently held by the pool.
+@item available
+Number of resources not currently checked out.
+@item waiters
+Number of fibers currently queued waiting for a resource.
+@item checkout-failure-count
+Cumulative number of checkouts where an exception was raised inside
+the proc.
+@end table
+
+Blocks waiting for the pool fiber to respond.  @code{#:timeout} is
+the number of seconds to wait; defaults to @code{5}.  Raises
+@code{&resource-pool-timeout} if the pool does not respond in time."
   (define channel
     (resource-pool-channel pool))
 

knots/sort.scm

@@ -54,6 +54,15 @@
                 rest)))))
 
 (define* (fibers-sort! items less #:key parallelism)
+  "Sort ITEMS destructively using LESS as the comparison procedure,
+using a parallel merge sort.  Returns the sorted list.
+
+Splits ITEMS into chunks, sorts each in an eager fiber-promise in
+parallel, then merges pairs of sorted chunks in parallel until one
+sorted list remains.
+
+@code{#:parallelism} sets the number of initial chunks.  Defaults to
+the current fibers parallelism."
   (define requested-chunk-count
     (or parallelism
         (+ 1 (length (scheduler-remote-peers (current-scheduler))))))