add some edits to the docs for response_adapter decorator; fix renderings

5 files changed, 40 insertions, 19 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 2bc462008..5ca9e9379 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,6 +4,10 @@ Next release
 Features
 --------
 
+- Added a decorator-based way to configure a response adapter:
+  ``pyramid.response.response_adapter``.  This decorator has the same use as
+  ``pyramid.config.Configurator.add_response_adapter`` but it's declarative.
+
 - The ``pyramid.events.BeforeRender`` event now has an attribute named
   ``rendering_val``.  This can be used to introspect the value returned by a
   view in a BeforeRender subscriber.
diff --git a/docs/glossary.rst b/docs/glossary.rst
index cc1d6201d..c6705fdc5 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -23,6 +23,11 @@ Glossary
      a subclass such as :class:`pyramid.httpexceptions.HTTPFound`.  See
      :ref:`webob_chapter` for information about response objects.
 
+   response adapter
+     A callable which accepts an arbitrary object and "converts" it to a
+     :class:`pyramid.response.Response` object.  See :ref:`using_iresponse`
+     for more information.
+
    Repoze
      "Repoze" is essentially a "brand" of software developed by `Agendaless
      Consulting <http://agendaless.com>`_ and a set of contributors.  The
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index df081d35c..fc3f01271 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -575,20 +575,6 @@ Response:
 
    config.add_response_adapter(string_response_adapter, str)
 
-The above example using the :class:`~pyramid.response.response_adapter`
-decorator:
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.response import Response
-   from pyramid.response import response_adapter
-
-   @response_adapter(str)
-   def string_response_adapter(s):
-       response = Response(s)
-       return response
-
 Likewise, if you want to be able to return a simplified kind of response
 object from view callables, you can use the IResponse hook to register an
 adapter to the more complex IResponse interface:
@@ -639,6 +625,29 @@ startup time, as by their nature, instances of this class (and instances of
 subclasses of the class) will natively provide IResponse.  The adapter
 registered for ``webob.Response`` simply returns the response object.
 
+Instead of using :meth:`pyramid.config.Configurator.add_response_adapter`,
+you can use the :class:`pyramid.response.response_adapter` decorator:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.response import Response
+   from pyramid.response import response_adapter
+
+   @response_adapter(str)
+   def string_response_adapter(s):
+       response = Response(s)
+       return response
+
+The above example, when scanned, has the same effect as:
+
+.. code-block:: python
+
+   config.add_response_adapter(string_response_adapter, str)
+
+The :class:`~pyramid.response.response_adapter` decorator will have no effect
+until activated by a :term:`scan`.
+
 .. index::
    single: view mapper
 
diff --git a/pyramid/config.py b/pyramid/config.py
index 46249d14e..b0041f370 100644
--- a/pyramid/config.py
+++ b/pyramid/config.py
@@ -661,7 +661,7 @@ class Configurator(object):
         """ Return a new Configurator instance with the same registry
         as this configurator using the package supplied as the
         ``package`` argument to the new configurator.  ``package`` may
-        be an actual Python package object or a Python dotted name
+        be an actual Python package object or a :term:`dotted Python name`
         representing a package."""
         context = self._ctx
         if context is None:
@@ -901,7 +901,7 @@ class Configurator(object):
         the server.
 
         A request handler factory (passed as ``handler_factory``) must be a
-        callable (or a :term:`Python dotted name` to a callable) which
+        callable (or a :term:`dotted Python name` to a callable) which
         accepts two arguments: ``handler`` and ``registry``.  ``handler``
         will be the request handler being wrapped.  ``registry`` will be the
         Pyramid :term:`application registry` represented by this
diff --git a/pyramid/response.py b/pyramid/response.py
index 60666bd03..db53de0c3 100644
--- a/pyramid/response.py
+++ b/pyramid/response.py
@@ -9,11 +9,11 @@ class Response(_Response):
 
 
 class response_adapter(object):
-    """ Decorator activated via a :term:`scan` which treats the
-    function being decorated as a response adapter for the set of types or
+    """ Decorator activated via a :term:`scan` which treats the function
+    being decorated as a :term:`response adapter` for the set of types or
     interfaces passed as ``*types_or_ifaces`` to the decorator constructor.
 
-    For example:
+    For example, if you scan the following response adapter:
 
     .. code-block:: python
 
@@ -24,6 +24,9 @@ class response_adapter(object):
         def myadapter(i):
             return Response(status=i)
 
+    You can then return an integer from your view callables, and it will be
+    converted into a response with the integer as the status code.
+
     More than one type or interface can be passed as a constructor argument.
     The decorated response adapter will be called for each type or interface.