1 files changed, 48 insertions, 6 deletions

diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md
index cbfa2e28..5b072827 100644
--- a/docs/api-guide/views.md
+++ b/docs/api-guide/views.md
@@ -27,14 +27,14 @@ For example:
         * Only admin users are able to access this view.
         """
         authentication_classes = (authentication.TokenAuthentication,)
-        permission_classes = (permissions.IsAdmin,)
+        permission_classes = (permissions.IsAdminUser,)
 
         def get(self, request, format=None):
             """
             Return a list of all users.
             """
-            users = [user.username for user in User.objects.all()]
-            return Response(users)
+            usernames = [user.username for user in User.objects.all()]
+            return Response(usernames)
 
 ## API policy attributes
 
@@ -118,9 +118,51 @@ You won't typically need to override this method.
 >
 > — [Nick Coghlan][cite2]
 
-REST framework also gives you to work with regular function based views...
+REST framework also allows you to work with regular function based views. It provides a set of simple decorators that wrap your function based views to ensure they receive an instance of `Request` (rather than the usual Django `HttpRequest`) and allows them to return a `Response` (instead of a Django `HttpResponse`), and allow you to configure how the request is processed.
 
-**[TODO]**
+## @api_view()
+
+**Signature:** `@api_view(http_method_names)`
+
+The core of this functionality is the `api_view` decorator, which takes a list of HTTP methods that your view should respond to. For example, this is how you would write a very simple view that just manually returns some data:
+
+    from rest_framework.decorators import api_view
+
+    @api_view(['GET'])
+    def hello_world(request):
+        return Response({"message": "Hello, world!"})
+
+
+This view will use the default renderers, parsers, authentication classes etc specified in the [settings](settings).
+
+## API policy decorators
+
+To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come *after* (below) the `@api_view` decorator. For example, to create a view that uses a [throttle](throttling) to ensure it can only be called once per day by a particular user, use the `@throttle_classes` decorator, passing a list of throttle classes:
+
+    from rest_framework.decorators import api_view, throttle_classes
+    from rest_framework.throttling import UserRateThrottle
+
+    class OncePerDayUserThrottle(UserRateThrottle):
+            rate = '1/day'
+
+    @api_view(['GET'])
+    @throttle_classes([OncePerDayUserThrottle])
+    def view(request):
+        return Response({"message": "Hello for today! See you tomorrow!"})
+
+These decorators correspond to the attributes set on `APIView` subclasses, described above.
+
+The available decorators are:
+
+* `@renderer_classes(...)`
+* `@parser_classes(...)`
+* `@authentication_classes(...)`
+* `@throttle_classes(...)`
+* `@permission_classes(...)`
+
+Each of these decorators takes a single argument which must be a list or tuple of classes.
 
 [cite]: http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html
-[cite2]: http://www.boredomandlaziness.org/2012/05/djangos-cbvs-are-not-mistake-but.html
\ No newline at end of file
+[cite2]: http://www.boredomandlaziness.org/2012/05/djangos-cbvs-are-not-mistake-but.html
+[settings]: api-guide/settings.md
+[throttling]: api-guide/throttling.md