From 95abe6e8445f59f9e52609b0c54d9276830dbfd3 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 25 Apr 2013 12:47:34 +0100
Subject: Cleanup docstrings

---
 rest_framework/viewsets.py | 48 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 13 deletions(-)

(limited to 'rest_framework/viewsets.py')

diff --git a/rest_framework/viewsets.py b/rest_framework/viewsets.py
index 28ab30e2..9133fd44 100644
--- a/rest_framework/viewsets.py
+++ b/rest_framework/viewsets.py
@@ -1,3 +1,21 @@
+"""
+ViewSets are essentially just a type of class based view, that doesn't provide
+any method handlers, such as `get()`, `post()`, etc... but instead has actions,
+such as `list()`, `retrieve()`, `create()`, etc...
+
+Actions are only bound to methods at the point of instantiating the views.
+
+    user_list = UserViewSet.as_view({'get': 'list'})
+    user_detail = UserViewSet.as_view({'get': 'retrieve'})
+
+Typically, rather than instantiate views from viewsets directly, you'll
+regsiter the viewset with a router and let the URL conf be determined
+automatically.
+
+    router = DefaultRouter()
+    router.register(r'users', UserViewSet, 'user')
+    urlpatterns = router.urls
+"""
 from functools import update_wrapper
 from django.utils.decorators import classonlymethod
 from rest_framework import views, generics, mixins
@@ -15,13 +33,10 @@ class ViewSetMixin(object):
 
     view = MyViewSet.as_view({'get': 'list', 'post': 'create'})
     """
-    _is_viewset = True
 
     @classonlymethod
     def as_view(cls, actions=None, name_suffix=None, **initkwargs):
         """
-        Main entry point for a request-response process.
-
         Because of the way class based views create a closure around the
         instantiated view, we need to totally reimplement `.as_view`,
         and slightly modify the view function that is created and returned.
@@ -64,12 +79,22 @@ class ViewSetMixin(object):
 
 
 class ViewSet(ViewSetMixin, views.APIView):
+    """
+    The base ViewSet class does not provide any actions by default.
+    """
+    pass
+
+
+class ReadOnlyModelViewSet(mixins.RetrieveModelMixin,
+                           mixins.ListModelMixin,
+                           ViewSetMixin,
+                           generics.GenericAPIView):
+    """
+    A viewset that provides default `list()` and `retrieve()` actions.
+    """
     pass
 
 
-# Note the inheritence of both MultipleObjectAPIView *and* SingleObjectAPIView
-# is a bit weird given the diamond inheritence, but it will work for now.
-# There's some implementation clean up that can happen later.
 class ModelViewSet(mixins.CreateModelMixin,
                     mixins.RetrieveModelMixin,
                     mixins.UpdateModelMixin,
@@ -77,11 +102,8 @@ class ModelViewSet(mixins.CreateModelMixin,
                     mixins.ListModelMixin,
                     ViewSetMixin,
                     generics.GenericAPIView):
-    pass
-
-
-class ReadOnlyModelViewSet(mixins.RetrieveModelMixin,
-                           mixins.ListModelMixin,
-                           ViewSetMixin,
-                           generics.GenericAPIView):
+    """
+    A viewset that provides default `create()`, `retrieve()`, `update()`,
+    `partial_update()`, `destroy()` and `list()` actions.
+    """
     pass
-- 
cgit v1.2.3