From de03880abeb1e91c5d4dffaaa0d26a5ee4e94e8e Mon Sep 17 00:00:00 2001
From: Andy Wingo <wingo@pobox.com>
Date: Thu, 7 Oct 2010 22:50:33 +0200
Subject: [PATCH] document trap states

* module/system/vm/trap-state.scm: Export add-trap!.

* doc/ref/api-debug.texi (Trap States): Document.
---
 doc/ref/api-debug.texi          | 29 +++++++++++++++++++++++++++++
 module/system/vm/trap-state.scm |  3 ++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index c577ca46d..e6fbc7893 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -1154,22 +1154,51 @@ directly, it doesn't compose well with traps at the REPL.
 @node Trap States
 @subsubsection Trap States
 
+When multiple traps are present in a system, we begin to have a
+bookkeeping problem. How are they named? How does one disable, enable,
+or delete them?
+
+Guile's answer to this is to keep an implicit per-thread @dfn{trap
+state}. The trap state object is not exposed to the user; rather, API
+that works on trap states fetches the current trap state from the
+dynamic environment.
+
+Traps identified by integers. A trap can be enabled, disabled, or
+removed, and can have an associated user-visible name.
+
+@deffn {Scheme Procedure} add-trap! trap name
+Add a trap to the current trap state, associating the given @var{name}
+with it. Returns a fresh trap identifier (an integer).
+
+Note that usually the more specific functions detailed in @ref{Setting
+Traps} are used in preference to this one.
+@end deffn
+
 @deffn {Scheme Procedure} list-traps
+List the current set of traps, both enabled and disabled. Returns a list
+of integers.
 @end deffn
 
 @deffn {Scheme Procedure} trap-name idx
+Returns the name associated with trap @var{idx}, or @code{#f} if there
+is no such trap.
 @end deffn
 
 @deffn {Scheme Procedure} trap-enabled? idx
+Returns @code{#t} if trap @var{idx} is present and enabled, or @code{#f}
+otherwise.
 @end deffn
 
 @deffn {Scheme Procedure} enable-trap! idx
+Enables trap @var{idx}.
 @end deffn
 
 @deffn {Scheme Procedure} disable-trap! idx
+Disables trap @var{idx}.
 @end deffn
 
 @deffn {Scheme Procedure} delete-trap! idx
+Removes trap @var{idx}, disabling it first, if necessary.
 @end deffn
 
 @node Trap Handlers
diff --git a/module/system/vm/trap-state.scm b/module/system/vm/trap-state.scm
index e9a2ad86c..435039aec 100644
--- a/module/system/vm/trap-state.scm
+++ b/module/system/vm/trap-state.scm
@@ -28,7 +28,8 @@
   #:use-module (system vm trace)
   #:use-module (system vm frame)
   #:use-module (system vm program)
-  #:export (list-traps
+  #:export (add-trap!
+            list-traps
             trap-enabled?
             trap-name
             enable-trap!