Add some documentation for the timeout procedures

And tweak how with-fibers-timeout works.

knots/timeout.scm

@@ -45,7 +45,16 @@
 
             with-port-timeouts))
 
-(define* (with-fibers-timeout thunk #:key timeout on-timeout)
+(define* (with-fibers-timeout thunk #:key
+                              timeout
+                              (on-timeout
+                               (const *unspecified*)))
+  "Run THUNK in a new fiber and return its values, waiting TIMEOUT
+seconds for it to finish.  If THUNK does not complete within TIMEOUT
+seconds, the ON-TIMEOUT procedure is called and with-fibers-timeout
+returns the result of ON-TIMEOUT instead.
+
+If THUNK raises an exception it is re-raised in the calling fiber."
   (let ((channel (make-channel)))
     (spawn-fiber
      (lambda ()
@@ -151,6 +160,21 @@
                              #:key timeout
                              (read-timeout timeout)
                              (write-timeout timeout))
+  "Run THUNK with per-operation I/O timeouts on all ports.  If any
+read or write blocks for longer than the given number of seconds, an
+exception is raised.
+
+@code{#:timeout} sets both read and write timeouts.
+@code{#:read-timeout} and @code{#:write-timeout} specify the timeout
+for reads and writes respectively.  All three default to @code{#f} (no
+timeout).
+
+This procedure works both with fibers, and without fibers by using the
+poll system call with a timeout.
+
+On read timeout, raises @code{&port-read-timeout-error}.  On write
+timeout, raises @code{&port-write-timeout-error}.  Both carry the
+@code{thunk} and @code{port} fields from @code{&port-timeout-error}."
   (define (no-fibers-wait thunk port mode timeout)
     (define poll-timeout-ms 200)