docs

1 files changed, 21 insertions, 12 deletions

diff --git a/pyramid/config.py b/pyramid/config.py
index c1adb51c9..918e3bce4 100644
--- a/pyramid/config.py
+++ b/pyramid/config.py
@@ -909,14 +909,14 @@ class Configurator(object):
     @action_method
     def add_tween(self, tween_factory):
         """
-        Add a 'tween factory'.  A :term`tween` (think: 'between') is a bit of
-        code that sits between the Pyramid router's main request handling
+        Add a 'tween factory'.  A :term:`tween` (think: 'between') is a bit
+        of code that sits between the Pyramid router's main request handling
         function and the upstream WSGI component that uses :app:`Pyramid` as
         its 'app'.  This is a feature that may be used by Pyramid framework
         extensions, to provide, for example, Pyramid-specific view timing
         support bookkeeping code that examines exceptions before they are
         returned to the upstream WSGI application.  Tweens behave a bit like
-        :mod:`WSGI` 'middleware' but they have the benefit of running in a
+        :term:`WSGI` 'middleware' but they have the benefit of running in a
         context in which they have access to the Pyramid :term:`application
         registry` as well as the Pyramid rendering machinery.
 
@@ -929,8 +929,9 @@ class Configurator(object):
         registry` represented by this Configurator.  A tween factory must
         return a tween when it is called.
 
-        A tween accepts a :term:`request` object and returns a two-tuple
-        consisting of a :term:`request` object and a :term:`response` object.
+        A tween is a callable which accepts a :term:`request` object and
+        returns a two-tuple consisting of a :term:`request` object and a
+        :term:`response` object.
 
         Here's an example creating a tween factory and registering it:
 
@@ -970,25 +971,33 @@ class Configurator(object):
         request handler as its ``handler`` argument, the second tween factory
         added will be called with the result of the first tween factory as
         its ``handler`` argument, and so on, ad infinitum. The Pyramid router
-        will use the outermost tween produced by this chain (the very last
-        tween added) as its request handler function.
+        will use the outermost tween produced by this chain (the tween
+        generated by the very last tween factory added) as its request
+        handler function.
 
         By default, the ordering of the chain is controlled entirely by the
         relative ordering of calls to ``add_tween``.  However, the deploying
         user can override tween inclusion and ordering in his Pyramid
         configuration using the ``pyramid.tweens`` settings value.  When
-        used, this settings value should be a list of Python dotted names
-        which imply the ordering (and inclusion) of tween factories in the
-        tween chain.
+        used, this settings value will be a list of Python dotted names which
+        imply the ordering (and inclusion) of tween factories in the tween
+        chain.
+
+        Note that Pyramid's own exception view handling logic is implemented
+        as a tween factory: ``pyramid.router.excview_tween_factory``.  If
+        Pyramid exception view handling is desired, and explicit tween
+        factories are specified via ``pyramid.tweens``, this function must be
+        added to the ``pyramid.tweens`` setting.  If it is not present,
+        Pyramid will not perform exception view handling.
 
         Pyramid will prevent the same tween factory from being added to the
         tween chain more than once using configuration conflict detection.
         If you wish to add the same tween factory more than once in a
         configuration, you should either: a) use a tween factory that is an
-        *instance* rather than a function or class, or b) use a function or
+        instance rather than a function or class, b) use a function or
         class as a tween factory with the same logic as the other tween
         factory it conflicts with but with a different ``__name__``
-        attribute.
+        attribute or c) call config.commit() between calls to ``add_tween``.
 
         A user can get a representation of both the implicit tween ordering
         (the ordering specified by calls to ``add_tween``) and the explicit