From d09c07fb102d3a151af9cac5bb6ffdc896f93ce1 Mon Sep 17 00:00:00 2001
From: Andy Wingo <wingo@pobox.com>
Date: Fri, 17 Dec 2010 13:14:13 +0100
Subject: [PATCH] document make-unbound-fluid et al

* doc/ref/api-scheduling.texi (Fluids and Dynamic States): Document the
  new fluid routines.

* NEWS: Update.
---
 NEWS                        |  6 ++----
 doc/ref/api-scheduling.texi | 20 +++++++++++++++++++-
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/NEWS b/NEWS
index 71dd8a41d..e9a8c3a4c 100644
--- a/NEWS
+++ b/NEWS
@@ -94,10 +94,8 @@ See FIXME in the manual, for more information.
 
 ** Add support for unbound fluids
     
-FIXME: needs documentation
-
-See `make-undefined-fluid' (FIXME: should be make-unbound-fluid),
-`fluid-unset!', and `fluid-bound?' in the manual.
+See `make-unbound-fluid', `fluid-unset!', and `fluid-bound?' in the
+manual.
 
 ** Add variable-unset!
     
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index d5504168c..a3bef7488 100644
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -691,6 +691,12 @@ inherits the values from its parent.  Because each thread normally executes
 with its own dynamic state, you can use fluids for thread local storage.
 @end deffn
 
+@deffn {Scheme Procedure} make-unbound-fluid
+@deffnx {C Function} scm_make_unbound_fluid ()
+Return a new fluid that is initially unbound (instead of being
+implicitly bound to @code{#f}.
+@end deffn
+
 @deffn {Scheme Procedure} fluid? obj
 @deffnx {C Function} scm_fluid_p (obj)
 Return @code{#t} iff @var{obj} is a fluid; otherwise, return
@@ -701,7 +707,8 @@ Return @code{#t} iff @var{obj} is a fluid; otherwise, return
 @deffnx {C Function} scm_fluid_ref (fluid)
 Return the value associated with @var{fluid} in the current
 dynamic root.  If @var{fluid} has not been set, then return
-@code{#f}.
+@code{#f}. Calling @code{fluid-ref} on an unbound fluid produces a
+runtime error.
 @end deffn
 
 @deffn {Scheme Procedure} fluid-set! fluid value
@@ -709,6 +716,17 @@ dynamic root.  If @var{fluid} has not been set, then return
 Set the value associated with @var{fluid} in the current dynamic root.
 @end deffn
 
+@deffn {Scheme Procedure} fluid-unset! fluid
+@deffnx {C Function} scm_fluid_unset_x (fluid)
+Disassociate the given fluid from any value, making it unbound.
+@end deffn
+
+@deffn {Scheme Procedure} fluid-bound? fluid
+@deffnx {C Function} scm_fluid_bound_p (fluid)
+Returns @code{#t} iff the given fluid is bound to a value, otherwise
+@code{#f}.
+@end deffn
+
 @code{with-fluids*} temporarily changes the values of one or more fluids,
 so that the given procedure and each procedure called by it access the
 given values.  After the procedure returns, the old values are restored.
-- 
2.20.1