Docs tweaking

docs/api-guide/authentication.md

@@ -39,6 +39,7 @@ You can also set the authentication policy on a per-view basis, using the `APIVi
 
     class ExampleView(APIView):
         authentication_classes = (SessionAuthentication, UserBasicAuthentication)
+        permission_classes = (IsAuthenticated,)
 
         def get(self, request, format=None):
             content = {
@@ -49,10 +50,9 @@ You can also set the authentication policy on a per-view basis, using the `APIVi
 
 Or, if you're using the `@api_view` decorator with function based views.
 
-    @api_view(
-        allowed=('GET',),
-        authentication_classes=(SessionAuthentication, UserBasicAuthentication)
-    )
+    @api_view('GET'),
+    @authentication_classes(SessionAuthentication, UserBasicAuthentication)
+    @permissions_classes(IsAuthenticated)
     def example_view(request, format=None):
         content = {
             'user': unicode(request.user),  # `django.contrib.auth.User` instance.

docs/api-guide/responses.md

@@ -8,18 +8,30 @@
 
 REST framework supports HTTP content negotiation by providing a `Response` class which allows you to return content that can be rendered into multiple content types, depending on the client request.
 
-The `Response` class subclasses Django's `TemplateResponse`.  `Response` objects are initialised with content, which should consist of native python primatives.  REST framework then uses standard HTTP content negotiation to determine how it should render the final response content.
+The `Response` class subclasses Django's `SimpleTemplateResponse`.  `Response` objects are initialised with data, which should consist of native python primatives.  REST framework then uses standard HTTP content negotiation to determine how it should render the final response content.
 
-There's no requirement for you to use the `Response` class, you can also return regular `HttpResponse` objects from your views if you want, but it does provide a better interface for returning Web API responses.
+There's no requirement for you to use the `Response` class, you can also return regular `HttpResponse` objects from your views if you want, but it provides a nicer interface for returning Web API responses.
 
-## Response(content, headers=None,  renderers=None, view=None, format=None, status=None)
+Unless you want to heavily customize REST framework for some reason, you should always use an `APIView` class or `@api_view` function for views that return `Response` objects.  Doing so ensures that the view can perform content negotiation and select the appropriate renderer for the response, before it is returned from the view.
 
+## Response(data, status=None, headers=None)
 
-## .renderers
+Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content.  Instead you pass in unrendered data, which may consist of any python primatives.
 
-## .view
+The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primative datatypes before creating the `Response` object.
 
-## .format
+You can use REST framework's `Serializer` classes to perform this data serialization, or use your own custom serialization.
 
+## .data
+
+The unrendered content of a `Request` object can be accessed using the `.data` attribute.
+
+## .content
+
+To access the rendered content of a `Response` object, you must first call `.render()`.  You'll typically only need to do this in cases such as unit testing responses - when you return a `Response` from a view Django's response cycle will handle calling `.render()` for you.
+
+## .renderer
+
+When you return a `Response` instance, the `APIView` class or `@api_view` decorator will select the appropriate renderer, and set the `.renderer` attribute on the `Response`, before returning it from the view.
 
 [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/

rest_framework/response.py

@@ -33,6 +33,8 @@ class Response(SimpleTemplateResponse):
 
     @property
     def rendered_content(self):
+        assert self.renderer, "No renderer set on Response"
+
         self['Content-Type'] = self.renderer.media_type
         if self.data is None:
             return self.renderer.render()