--- a/docs.txt	Thu Sep 10 17:05:05 2009 -0700
+++ b/docs.txt	Thu Sep 10 22:32:45 2009 -0700
@@ -6,6 +6,14 @@
 provides convenient, secure object wrapping between JS and Python
 space.
 
+Note that Pydertron is just one example of a high-level interface
+between Python and JavaScript: it assumes, for instance, that the JS
+code it executes isn't trusted, which affects the nature of the
+inter-language interaction.
+
+The Basics
+----------
+
 The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
 object, and a simple `SecurableModule`__ implementation that complies
 with the `CommonJS`__ standard. It also provides a high-level bridge between
@@ -77,7 +85,36 @@
   ReferenceError: bar is not defined
   -1
 
-Note that the traceback displayed is actually referring to
-JavaScript code: one of Pydertron's helpful conveniences is that
-it makes debugging JS code as much like debugging Python code as
-possible.
+Note that the traceback displayed is actually referring to JavaScript
+code: one of Pydertron's aims is to make debugging JS code as much
+like debugging Python code as possible.
+
+Exceptions
+----------
+
+Any exceptions raised by wrapped Python functions need to be of type
+``pydermonkey.error`` to be propagated into calling JavaScript code;
+if they're not, then for security purposes, the entire JavaScript call
+stack is unrolled.
+
+For example, here's a function that's bound to fail:
+
+  >>> @jsexposed
+  ... def fail():
+  ...   o()
+  >>> sandbox.root.fail = fail
+
+Now, even though the following JS code calls the function in a
+try-catch block, the JS code doesn't catch anything and its execution
+is simply halted:
+
+  >>> sandbox.run_script("try { fail(); } catch (e) {}",
+  ...                    stderr=sys.stdout)  #doctest: +ELLIPSIS
+  An internal error occurred.
+  Traceback (most recent call last):
+  ...
+  NameError: global name 'o' is not defined
+  -1
+
+Note that a ``KeyboardInterrupt`` triggered while JS is executing will
+have similar effect.