More docs.

4 files changed, 39 insertions, 4 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 73b6b0be4..abef4ab0e 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -21,9 +21,10 @@ Features
   arguments: ``context`` and ``request`` and returns ``True`` or
   ``False``).  The associated route will match will only be invoked if
   all custom predicates return ``True``, else route matching
-  continues.  Use one or more custom predicates when no existing
-  predefined predicate is useful.  Predefined and custom predicates
-  can be mixed freely.
+  continues.  Note that the value ``context`` will always be ``None``
+  when passed to a custom route predicate.  Use one or more custom
+  predicates when no existing predefined predicate is useful.
+  Predefined and custom predicates can be mixed freely.
 
 1.2a6 (2009-12-18)
 ==================
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index ad0388284..fbf3901be 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -163,6 +163,22 @@ accept
 
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
+custom_predicates
+
+  This value should be a sequence of references to custom predicate
+  callables.  Use custom predicates when no set of predefined
+  predicates does what you need.  Custom predicates can be combined
+  with predefined predicates as necessary.  Each custom predicate
+  callable should accept two arguments: ``context`` and ``request``
+  and should return either ``True`` or ``False`` after doing arbitrary
+  evaluation of the context and/or the request.  If all callables
+  return ``True``, the associated route will be considered viable for
+  a given request.  If any custom predicate returns ``False``, route
+  matching continues.  Note that the value ``context`` will always be
+  ``None`` when passed to a custom route predicate.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
+
 view_for
 
   The Python dotted-path name to a class or an interface that the
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 01389cec0..678888872 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -555,6 +555,22 @@ path_info
 
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
+custom_predicates
+
+  This value should be a sequence of references to custom predicate
+  callables (e.g. ``dotted.name.one dotted.name.two``, if used in
+  ZCML; Python dotted names to callables separated by spaces).  Use
+  custom predicates when no set of predefined predicates do what you
+  need.  Custom predicates can be combined with predefined predicates
+  as necessary.  Each custom predicate callable should accept two
+  arguments: ``context`` and ``request`` and should return either
+  ``True`` or ``False`` after doing arbitrary evaluation of the
+  context and/or the request.  If all callables return ``True``, the
+  associated view callable will be considered viable for a given
+  request.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
+
 .. _mapping_views_to_urls_using_a_decorator_section:
 
 View Configuration Using the ``@bfg_view`` Decorator
diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index f135b2ee2..467ccfe13 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -814,7 +814,9 @@ class Configurator(object):
           the context and/or the request.  If all callables return
           ``True``, the associated route will be considered viable for
           a given request.  If any custom predicate returns ``False``,
-          route matching continues.
+          route matching continues.  Note that the value ``context``
+          will always be ``None`` when passed to a custom route
+          predicate.
 
         View-Related Arguments