- Added API docs for the ``repoze.bfg.testing`` methods

  ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and
  ``cleanUp``.

- Added glossary entry for "root factory".

4 files changed, 73 insertions, 3 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index b62768d42..461cbc560 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,5 +1,17 @@
+0.8dev
+======
+
+Documentation
+-------------
+
+- Added API docs for the ``repoze.bfg.testing`` methods
+  ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and
+  ``cleanUp``.
+
+- Added glossary entry for "root factory".
+
 0.8a6 (2009-05-11)
--------------------
+==================
 
 Features
 --------
@@ -41,7 +53,7 @@ Bug Fixes
   part of the final Routes 1.11 release.
 
 0.8a5 (2009-05-08)
-------------------
+==================
 
 Features
 --------
diff --git a/docs/api/testing.rst b/docs/api/testing.rst
index 9aebc7d30..7870ed1d3 100644
--- a/docs/api/testing.rst
+++ b/docs/api/testing.rst
@@ -17,6 +17,14 @@
 
   .. autofunction:: registerViewPermission
 
+  .. autofunction:: registerUtility
+
+  .. autofunction:: registerAdapter
+
+  .. autofunction:: registerSubscriber
+
+  .. autofunction:: cleanUp
+
   .. autoclass:: DummyModel
      :members:
 
diff --git a/docs/glossary.rst b/docs/glossary.rst
index b55f8395c..6d4d83f51 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -338,3 +338,13 @@ Glossary
     itself, its parent, its parent's parent, and so on.  The order of
     the sequence is context-first, then the parent of the context,
     then its parent's parent, and so on.
+  Root Factory
+    The "root factory" of an :mod:`repoze.bfg` application is called
+    on every request sent to the application.  The root factory
+    returns the traversal root of an application.  It is
+    conventionally named ``get_root``.  An application must supply a
+    root factory to :mod:`repoze.bfg` within a call to
+    ``repoze.bfg.router.make_app``; however, an application's root
+    factory may be passed to ``make_app`` as ``None``, in which case
+    the application performs no graph traversal and uses :term:`URL
+    dispatch` for all URL-to-view code mappings.
diff --git a/repoze/bfg/testing.py b/repoze/bfg/testing.py
index 42d5e88fd..0ff1dbade 100644
--- a/repoze/bfg/testing.py
+++ b/repoze/bfg/testing.py
@@ -106,12 +106,35 @@ def registerViewPermission(name, result=True, viewpermission=None,
     return registerAdapter(viewpermission, for_, IViewPermission, name)
 
 def registerUtility(impl, iface=Interface, name=''):
+    """ Register a Zope component architecture utility component.
+    This is exposed as a convenience in this package to avoid needing
+    to import the ``registerUtility`` function from ``zope.component``
+    within unit tests that make use of the ZCA.  ``impl`` is the
+    implementation of the utility.  ``iface`` is the interface type
+    ``zope.interface.Interface`` by default.  ``name`` is the empty
+    string by default.  See `The ZCA book
+    <http://www.muthukadan.net/docs/zca.html>`_ for more information
+    about ZCA utilities."""
     import zope.component 
     gsm = zope.component.getGlobalSiteManager()
     gsm.registerUtility(impl, iface, name=name)
     return impl
 
 def registerAdapter(impl, for_=Interface, provides=Interface, name=''):
+    """ Register a Zope component architecture adapter component.
+    This is exposed as a convenience in this package to avoid needing
+    to import the ``registerAdapter`` function from ``zope.component``
+    within unit tests that make use of the ZCA.  ``impl`` is the
+    implementation of the component (often a class).  ``for_`` is the
+    ``for`` interface type ``zope.interface.Interface`` by default. If
+    ``for`` is not a tuple or list, it will be converted to a
+    one-tuple before being passed to underlying ZCA registerAdapter
+    API.  ``name`` is the empty string by default.  ``provides`` is
+    the ZCA provides interface, also ``zope.interface.Interface`` by
+    default.  ``name`` is the name of the adapter, the empty string by
+    default.  See `The ZCA book
+    <http://www.muthukadan.net/docs/zca.html>`_ for more information
+    about ZCA adapters."""
     import zope.component
     gsm = zope.component.getGlobalSiteManager()
     if not isinstance(for_, (tuple, list)):
@@ -120,6 +143,17 @@ def registerAdapter(impl, for_=Interface, provides=Interface, name=''):
     return impl
 
 def registerSubscriber(subscriber, iface=Interface):
+    """ Register a Zope component architecture subscriber component.
+    This is exposed as a convenience in this package to avoid needing
+    to import the ``registerHandler`` function from ``zope.component``
+    within unit tests that make use of the ZCA.  ``subscriber`` is the
+    implementation of the component (often a function).  ``iface`` is
+    the interface type the subscriber will be registered for
+    (``zope.interface.Interface`` by default). If ``iface`` is not a
+    tuple or list, it will be converted to a one-tuple before being
+    passed to underlying zca registerHandler query.  See `The ZCA book
+    <http://www.muthukadan.net/docs/zca.html>`_ for more information
+    about ZCA subscribers."""
     import zope.component
     gsm = zope.component.getGlobalSiteManager()
     if not isinstance(iface, (tuple, list)):
@@ -382,7 +416,13 @@ def addCleanUp(func, args=(), kw={}):
     _cleanups.append((func, args, kw))
 
 def cleanUp():
-    """Clean up global data."""
+    """Clean up BFG testing registrations.  Use in the ``tearDown`` of
+    unit tests that use the ``register*`` methods in the testing
+    module (e.g. if your unit test uses
+    ``repoze.bfg.testing.registerDummyRenderer`` or
+    ``repoze.bfg.testing.registerDummySecurityPolicy``).  If you use
+    the ``register*`` functions without calling cleanUp, unit tests
+    will not be isolated with respect to registrations they perform."""
     for func, args, kw in _cleanups:
         func(*args, **kw)