More docs.

3 files changed, 59 insertions, 34 deletions

diff --git a/docs/api/testing.rst b/docs/api/testing.rst
index da0a128d9..2b6e1f8ae 100644
--- a/docs/api/testing.rst
+++ b/docs/api/testing.rst
@@ -5,6 +5,22 @@
 
 .. automodule:: repoze.bfg.testing
 
-  .. autoclass:: BFGTestCase
+  .. autofunction:: registerDummySecurityPolicy
+
+  .. autofunction:: registerModels
+
+  .. autofunction:: registerEventListener
+
+  .. autofunction:: registerTemplateRenderer
+
+  .. autofunction:: registerView
+
+  .. autofunction:: registerViewPermission
+
+  .. autoclass:: DummyModel
+     :members:
+
+  .. autoclass:: DummyRequest
      :members:
 
+
diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst
index 1e1b23b9f..8e9894c3f 100644
--- a/docs/narr/unittesting.rst
+++ b/docs/narr/unittesting.rst
@@ -30,10 +30,10 @@ Without invoking any ZCML or using the testing API, an attempt to run
 this view function will result in an error.  When a :mod:`repoze.bfg`
 application starts normally, it will create an application registry
 from the information it finds in the application's ``configure.zcml``
-file.  If this application registry is not created and populated
-(e.g. with ``bfg:view`` statements), such as when you invoke
-application code via unit tests, :mod:`repoze.bfg` API functions will
-tend to fail.
+file.  But if this application registry is not created and populated
+(e.g. with ``bfg:view`` statements), like when you invoke application
+code via a unit test, :mod:`repoze.bfg` API functions will tend to
+fail.
 
 The testing API provided by ``repoze.bfg`` allows you to simulate
 various application registry registrations for use under a unit
@@ -47,7 +47,7 @@ unittest TestCase that used the testing API.
 
    import unittest
    from zope.testing.cleanup import cleanUp
-   from.repoze.bfg import testing
+   from repoze.bfg import testing
 
    class MyTest(unittest.TestCase):
        def setUp(self):
@@ -57,13 +57,15 @@ unittest TestCase that used the testing API.
            cleanUp()
        
        def test_view_fn_not_submitted(self):
+           from my.package import view_fn
            renderer = testing.registerTemplateRenderer('templates/show.pt')
            context = testing.DummyModel()
            request = testing.DummyRequest()
            response = view_fn(context, request)
            self.assertEqual(renderer.say, 'Hello')
 
-        def test_view_fn_submitted(self):
+       def test_view_fn_submitted(self):
+           from my.package import view_fn
            renderer = testing.registerTemplateRenderer('templates/submitted.pt')
            context = testing.DummyModel()
            request = testing.DummyRequest()
diff --git a/repoze/bfg/testing.py b/repoze/bfg/testing.py
index 55ecc6d17..39341c301 100644
--- a/repoze/bfg/testing.py
+++ b/repoze/bfg/testing.py
@@ -7,15 +7,15 @@ def registerDummySecurityPolicy(userid=None, groupids=(), permissive=True):
     """ Registers a dummy ``repoze.bfg`` security policy using the
     userid ``userid`` and the group ids ``groupids``.  If
     ``permissive`` is true, a 'permissive' security policy is
-    registered; this policy allows all access.  If ``permissive``
-    is false, a nonpermissive security policy is registered; this
-    policy denies all access.  To register your own (possibly more
-    granular) security policy, see the ``registerSecurityPolicy``
-    *function* in the testing package.  This function is most
-    useful when dealing with code that uses the
-    ``repoze.bfg.security``APIs named ``has_permission``,
-    ``authenticated_userid``, effective_principals, and
-    ``principals_allowed_by_permission``."""
+    registered; this policy allows all access.  If ``permissive`` is
+    false, a nonpermissive security policy is registered; this policy
+    denies all access.  This function is most useful when testing code
+    that uses the ``repoze.bfg.security`` APIs named
+    ``has_permission``, ``authenticated_userid``,
+    effective_principals, and ``principals_allowed_by_permission``.
+    To register your own (possibly more granular) security policy, see
+    the ``registerSecurityPolicy`` function in the testing package
+    (read the source)."""
     if permissive:
         policy = DummyAllowingSecurityPolicy(userid, groupids)
     else:
@@ -24,10 +24,10 @@ def registerDummySecurityPolicy(userid=None, groupids=(), permissive=True):
 
 def registerModels(models):
     """ Registers a dictionary of models.  This is most useful for
-    dealing with code that wants to call the
-    ``repoze.bfg.traversal.find_model`` API.  This API is called
-    with a path as one of its arguments.  If the dictionary you
-    register when calling this method contains that path as a key
+    testing code that wants to call the
+    ``repoze.bfg.traversal.find_model`` API.  This API is called with
+    a path as one of its arguments.  If the dictionary you register
+    when calling this method contains that path as a key
     (e.g. '/foo/bar' or 'foo'), the corresponding value will be
     returned to ``find_model`` (and thus to your code)."""
     traverser = make_traverser_factory(models)
@@ -35,14 +35,13 @@ def registerModels(models):
     return models
 
 def registerEventListener(event_iface=Interface):
-    """ Registers an event listener (aka 'subscriber') listening
-    for events of the type ``event_iface`` and returns a list
-    which is appended to by the subscriber.  When an event is
-    dispatched that matches ``event_iface``, that event will be
-    appended to the list.  You can then compare the values in the
-    list to expected event notifications.  This method is useful
-    when dealing with code that wants to call
-    ``zope.component.event.dispatch``."""
+    """ Registers an event listener (aka 'subscriber') listening for
+    events of the type ``event_iface`` and returns a list which is
+    appended to by the subscriber.  When an event is dispatched that
+    matches ``event_iface``, that event will be appended to the list.
+    You can then compare the values in the list to expected event
+    notifications.  This method is useful when testing code that wants
+    to call ``zope.component.event.dispatch``."""
     L = []
     def subscriber(event):
         L.append(event)
@@ -52,9 +51,11 @@ def registerEventListener(event_iface=Interface):
 def registerTemplateRenderer(path, renderer=None, for_=None):
     """ Create and register a dummy template renderer at ``path``
     (usually a relative filename ala ``templates/foo.pt``) and return
-    the renderer object.  If ``renderer`` is non-None, it will be
+    the renderer object.  If ``renderer`` is not ``None``, it will be
     registered as the renderer and returned (no dummy renderer object
-    will be created)."""
+    will be created).  This function is useful when testing code that
+    calls the ``render_template_to_response`` or any other
+    ``render_template*`` API of the built-in templating systems. """
     if for_ is None:
         from repoze.bfg.interfaces import ITestingTemplateRenderer
         for_ = ITestingTemplateRenderer
@@ -68,8 +69,8 @@ def registerView(name, result='', view=None, for_=(Interface, Interface)):
     ``result`` value as its body attribute.  To gain more control, if
     you pass in a non-None ``view``, this view function will be used
     instead of an automatically generated view function (and
-    ``result`` is not used).  This method is useful when dealing with
-    code that wants to call,
+    ``result`` is not used).  This function is useful when dealing
+    with code that wants to call,
     e.g. ``repoze.bfg.view.render_view_to_response``."""
     if view is None:
         view = make_view(result)
@@ -200,7 +201,10 @@ def make_view_permission(result):
     return DummyViewPermission
         
 class DummyModel:
-    """ A dummy :mod:`repoze.bfg` model object """
+    """ A dummy :mod:`repoze.bfg` model object.  The value of ``name``
+    to the constructor will be used as the ``__name__`` attribute of
+    the model.  the value of ``parent`` will be used as the
+    ``__parent__`` attribute of the model. """
     def __init__(self, name=None, parent=None):
         """ The he model's ``__name__`` attribute will be set to the
         value of ``name``, and the model's ``__parent__`` attribute
@@ -228,7 +232,10 @@ class DummyModel:
         return ob
     
 class DummyRequest:
-    """ A dummy request object (imitates a WebOb request object) """
+    """ A dummy request object (imitates a :term:`WebOb` ``Request``
+    object).  The named constructor arguments correspond to their
+    WebOb equivalents.  Extra keyword arguments are assigned as
+    attributes of the request itself."""
     implements(IRequest)
     method = 'GET'
     application_url = 'http://example.com'