Add even more documentation

knots.scm

@@ -29,6 +29,11 @@
             spawn-fiber/knots))
 
 (define (call-with-default-io-waiters thunk)
+  "Run THUNK with Guile's default blocking I/O waiters active.
+
+This is useful when restoring the default Guile I/O waiters from
+within a context (like Fibers) where different I/O waiters are used,
+for example when creating a new thread from a fiber."
   (parameterize
       ((current-read-waiter (@@ (ice-9 suspendable-ports)
                                 default-read-waiter))
@@ -37,6 +42,11 @@
     (thunk)))
 
 (define (wait-when-system-clock-behind)
+  "Block until the system clock reads at least 2001-01-02.
+
+Useful at startup in environments (virtual machines, embedded systems)
+where the clock may start at or near the Unix epoch.  Prints a warning
+to the current error port every 20 seconds while waiting."
   ;; Jan 02 2001 02:00:00
   (let ((start-of-the-year-2001 978400800))
     (while (< (current-time)
@@ -47,6 +57,18 @@
 
 ;; Copied from (fibers web server)
 (define (call-with-sigint thunk cvar)
+  "Run THUNK with a SIGINT handler that signals the Fibers condition
+CVAR.  Restores the previous handler when THUNK returns.
+
+Typical usage is to pass a condition variable to this procedure and
+wait on CVAR in a fiber to implement clean shutdown on Ctrl-C:
+
+@example
+(let ((quit-cvar (make-condition)))
+  (call-with-sigint
+    (lambda () (wait quit-cvar))
+    quit-cvar))
+@end example"
   (let ((handler #f))
     (dynamic-wind
       (lambda ()
@@ -97,6 +119,11 @@
        (raise-exception exn)))))
 
 (define* (display/knots obj #:optional (port (current-output-port)))
+  "Write OBJ to PORT (default: current output port) as a UTF-8 byte
+sequence via @code{put-bytevector}.
+
+When used with ports without buffering, this should be safer than
+display."
   (put-bytevector
    port
    (string->utf8
@@ -105,6 +132,8 @@
         (display obj port))))))
 
 (define (simple-format/knots port s . args)
+  "Like @code{simple-format} but should be safer when used with a port
+without buffering."
   (let ((str (apply simple-format #f s args)))
     (if (eq? #f port)
         str
@@ -115,6 +144,8 @@
              port)))))
 
 (define (format/knots port s . args)
+  "Like @code{format} but should be safer when used with a port
+without buffering."
   (let ((str (apply format #f s args)))
     (if (eq? #f port)
         str
@@ -233,6 +264,10 @@
     (display/knots error-string port)))
 
 (define* (spawn-fiber/knots thunk #:optional scheduler #:key parallel?)
+  "Spawn a fiber to run THUNK, with knots exception handling.
+
+Accepts the same optional SCHEDULER and @code{#:parallel?} arguments
+as @code{spawn-fiber}."
   (spawn-fiber
    (lambda ()
      (with-exception-handler