Fixed #17035, #17036 -- Clarified documentation regarding TemplateResponse and middleware handling. Refs #16004. Thanks ptone.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16961 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/ref/request-response.txt

@@ -758,3 +758,10 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in
 .. class:: HttpResponseServerError
 
     Acts just like :class:`HttpResponse` but uses a 500 status code.
+
+.. note::
+
+    If a custom subclass of :class:`HttpResponse` implements a ``render``
+    method, Django will treat it as emulating a
+    :class:`~django.template.response.SimpleTemplateResponse`, and the
+    ``render`` method must itself return a valid response object.

docs/ref/template-response.txt

@@ -126,7 +126,8 @@ Methods
 .. method:: SimpleTemplateResponse.render():
 
     Sets :attr:`response.content` to the result obtained by
-    :attr:`SimpleTemplateResponse.rendered_content`.
+    :attr:`SimpleTemplateResponse.rendered_content`, runs all post-rendering
+    callbacks, and returns the resulting response object.
 
     :meth:`~SimpleTemplateResponse.render()` will only have an effect
     the first time it is called. On subsequent calls, it will return

docs/topics/http/middleware.txt

@@ -121,22 +121,20 @@ middleware is always called on every response.
 
 .. method:: process_template_response(self, request, response)
 
-``request`` is an :class:`~django.http.HttpRequest` object. ``response`` is the
+``request`` is an :class:`~django.http.HttpRequest` object. ``response`` is a
-:class:`~django.template.response.SimpleTemplateResponse` subclass (e.g.
+subclass of :class:`~django.template.response.SimpleTemplateResponse` (e.g.
-:class:`~django.template.response.TemplateResponse`) object returned by a
+:class:`~django.template.response.TemplateResponse`) or any response object
-Django view.
+that implements a ``render`` method.
 
-``process_template_response()`` must return an
+``process_template_response()`` must return a response object that implements a
-:class:`~django.template.response.SimpleTemplateResponse` (or its subclass)
+``render`` method. It could alter the given ``response`` by changing
-object. It could alter the given ``response`` by changing
+``response.template_name`` and ``response.context_data``, or it could create
-``response.template_name`` and ``response.context_data``, or it could
+and return a brand-new
-create and return a brand-new
+:class:`~django.template.response.SimpleTemplateResponse` or equivalent.
-:class:`~django.template.response.SimpleTemplateResponse` (or its subclass)
-instance.
 
 ``process_template_response()`` will only be called if the response
 instance has a ``render()`` method, indicating that it is a
-:class:`~django.template.response.TemplateResponse`.
+:class:`~django.template.response.TemplateResponse` or equivalent.
 
 You don't need to explicitly render responses -- responses will be
 automatically rendered once all template response middleware has been