Add more documentation

knots/promise.scm

@@ -41,12 +41,21 @@
   (evaluated-condition  fibers-promise-evaluated-condition))
 
 (define (fibers-delay thunk)
+  "Return a new fiber-aware promise that will evaluate THUNK when
+first forced.  THUNK is not called until @code{fibers-force} is
+called on the promise."
   (make-fibers-promise
    thunk
    (make-atomic-box #f)
    (make-condition)))
 
 (define (fibers-force fp)
+  "Force the fiber-aware promise FP, returning its values.
+
+The first call evaluates the promise's thunk.  Concurrent callers
+block on a condition variable until evaluation finishes, then receive
+the same result.  If the thunk raises an exception, the exception is
+stored and re-raised for all callers."
   (unless (fibers-promise? fp)
     (raise-exception
      (make-exception
@@ -108,6 +117,9 @@
 
 
 (define (fibers-delay/eager thunk)
+  "Return a new fiber-aware promise and immediately begin evaluating
+THUNK in a new fiber.  Exceptions during eager evaluation are silently
+discarded; they will be re-raised when @code{fibers-force} is called."
   (let ((promise (fibers-delay thunk)))
     (spawn-fiber
      (lambda ()
@@ -121,10 +133,15 @@
     promise))
 
 (define (fibers-promise-reset fp)
+  "Reset the fiber-aware promise FP so that the next call to
+@code{fibers-force} re-evaluates its thunk."
   (atomic-box-set! (fibers-promise-values-box fp)
                    #f))
 
 (define (fibers-promise-result-available? fp)
+  "Return @code{#t} if the fiber-aware promise FP has been evaluated
+(successfully or with an exception) and @code{#f} if evaluation has
+not yet started or is still in progress."
   (let ((val (atomic-box-ref (fibers-promise-values-box fp))))
     (not (or (eq? val #f)
              (eq? val 'started)))))