Updated the docs with the new over/under tuples.

2 files changed, 24 insertions, 10 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index f81385c93..fafb407d3 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -948,6 +948,10 @@ Allowable values for ``under`` or ``over`` (or both) are:
 - One of the constants :attr:`pyramid.tweens.MAIN`,
   :attr:`pyramid.tweens.INGRESS`, or :attr:`pyramid.tweens.EXCVIEW`.
 
+- An iterable of any combination of the above. This allows the user to specify
+  fallbacks if the desired tween is not included, as well as compatibility
+  with multiple other tweens.
+
 Effectively, ``under`` means "closer to the main Pyramid application than",
 ``over`` means "closer to the request ingress than".
 
@@ -999,10 +1003,14 @@ this::
 Specifying neither ``over`` nor ``under`` is equivalent to specifying
 ``under=INGRESS``.
 
-If an ``under`` or ``over`` value is provided that does not match a tween
-factory dotted name or alias in the current configuration, that value will be
-ignored.  It is not an error to provide an ``under`` or ``over`` value that
-matches an unused tween factory.
+If all options for ``under`` (or ``over``) cannot be found in the current
+configuration, it is an error. If some options are specified purely for
+compatibilty with other tweens, just add a fallback of MAIN or INGRESS.
+For example, ``under=('someothertween', 'someothertween2', INGRESS)``.
+This constraint will require the tween to be located under both the
+'someothertween' tween, the 'someothertween2' tween, and INGRESS. If any of
+these is not in the current configuration, this constraint will only organize
+itself based on the tweens that are present.
 
 :meth:`~pyramid.config.Configurator.add_tween` also accepts an ``alias``
 argument.  If ``alias`` is not ``None``, should be a string.  The string will
diff --git a/pyramid/config.py b/pyramid/config.py
index d6e9fd11c..3c6e8db6f 100644
--- a/pyramid/config.py
+++ b/pyramid/config.py
@@ -996,8 +996,9 @@ class Configurator(object):
         - One of the constants :attr:`pyramid.tweens.MAIN`,
           :attr:`pyramid.tweens.INGRESS`, or :attr:`pyramid.tweens.EXCVIEW`.
 
-        - A tuple of any combination of the above. This allows the user
-          to specify fallbacks if the desired tween is not included.
+        - An iterable of any combination of the above. This allows the user
+          to specify fallbacks if the desired tween is not included, as well
+          as compatibility with multiple other tweens.
         
         ``under`` means 'closer to the main Pyramid application than',
         ``over`` means 'closer to the request ingress than'.
@@ -1011,10 +1012,15 @@ class Configurator(object):
         fictional) 'someothertween' tween factory (which was presumably added
         via ``add_tween(factory, alias='someothertween')``).
 
-        If an ``under`` or ``over`` value is provided that does not match a
-        tween factory dotted name or alias in the current configuration, that
-        value will be ignored.  It is not an error to provide an ``under`` or
-        ``over`` value that matches an unused tween factory.
+        If all options for ``under`` (or ``over``) cannot be found in the
+        current configuration, it is an error. If some options are specified
+        purely for compatibilty with other tweens, just add a fallback of
+        MAIN or INGRESS. For example,
+        ``under=('someothertween', 'someothertween2', INGRESS)``.
+        This constraint will require the tween to be located under both the
+        'someothertween' tween, the 'someothertween2' tween, and INGRESS. If
+        any of these is not in the current configuration, this constraint will
+        only organize itself based on the tweens that are present.
 
         Specifying neither ``over`` nor ``under`` is equivalent to specifying
         ``under=INGRESS``.