Cleanup docstrings

docs/api-guide/viewsets.md

@@ -41,6 +41,10 @@ If we need to, we can bind this viewset into two seperate views, like so:
 
 Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated.
 
+    router = DefaultRouter()
+    router.register(r'users', UserViewSet, 'user')
+    urlpatterns = router.urls
+
 There are two main advantages of using a `ViewSet` class over using a `View` class.
 
 * Repeated logic can be combined into a single class.  In the above example, we only need to specify the `queryset` once, and it'll be used across multiple views.

rest_framework/authentication.py

@@ -1,5 +1,5 @@
 """
-Provides a set of pluggable authentication policies.
+Provides various authentication policies.
 """
 from __future__ import unicode_literals
 import base64

rest_framework/decorators.py

@@ -1,3 +1,11 @@
+"""
+The most imporant decorator in this module is `@api_view`, which is used
+for writing function-based views with REST framework.
+
+There are also various decorators for setting the API policies on function
+based views, as well as the `@action` and `@link` decorators, which are
+used to annotate methods on viewsets that should be included by routers.
+"""
 from __future__ import unicode_literals
 from rest_framework.compat import six
 from rest_framework.views import APIView

rest_framework/fields.py

@@ -1,3 +1,8 @@
+"""
+Serializer fields perform validation on incoming data.
+
+They are very similar to Django's form fields.
+"""
 from __future__ import unicode_literals
 
 import copy

rest_framework/filters.py

@@ -1,3 +1,7 @@
+"""
+Provides generic filtering backends that can be used to filter the results
+returned by list views.
+"""
 from __future__ import unicode_literals
 from rest_framework.compat import django_filters
 

rest_framework/generics.py

@@ -10,8 +10,6 @@ from django.http import Http404
 from django.shortcuts import get_object_or_404
 from django.utils.translation import ugettext as _
 
-### Base classes for the generic views ###
-
 
 class GenericAPIView(views.APIView):
     """

rest_framework/negotiation.py

@@ -1,3 +1,7 @@
+"""
+Content negotiation deals with selecting an appropriate renderer given the
+incoming request.  Typically this will be based on the request's Accept header.
+"""
 from __future__ import unicode_literals
 from django.http import Http404
 from rest_framework import exceptions

rest_framework/pagination.py

@@ -1,9 +1,11 @@
+"""
+Pagination serializers determine the structure of the output that should
+be used for paginated responses.
+"""
 from __future__ import unicode_literals
 from rest_framework import serializers
 from rest_framework.templatetags.rest_framework import replace_query_param
 
-# TODO: Support URLconf kwarg-style paging
-
 
 class NextPageField(serializers.Field):
     """

rest_framework/relations.py

@@ -1,3 +1,9 @@
+"""
+Serializer fields that deal with relationships.
+
+These fields allow you to specify the style that should be used to represent
+model relationships, including hyperlinks, primary keys, or slugs.
+"""
 from __future__ import unicode_literals
 from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.core.urlresolvers import resolve, get_script_prefix, NoReverseMatch

rest_framework/request.py

@@ -1,11 +1,10 @@
 """
-The :mod:`request` module provides a :class:`Request` class used to wrap the standard `request`
+The Request class is used as a wrapper around the standard request object.
-object received in all the views.
 
 The wrapped request then offers a richer API, in particular :
 
     - content automatically parsed according to `Content-Type` header,
-      and available as :meth:`.DATA<Request.DATA>`
+      and available as `request.DATA`
     - full support of PUT method, including support for file uploads
     - form overloading of HTTP method, content type and content
 """

rest_framework/response.py

@@ -1,3 +1,9 @@
+"""
+The Response class in REST framework is similiar to HTTPResponse, except that
+it is initialized with unrendered data, instead of a pre-rendered string.
+
+The appropriate renderer is called during Django's template response rendering.
+"""
 from __future__ import unicode_literals
 from django.core.handlers.wsgi import STATUS_CODE_TEXT
 from django.template.response import SimpleTemplateResponse

rest_framework/serializers.py

@@ -1,3 +1,15 @@
+"""
+Serializers and ModelSerializers are similar to Forms and ModelForms.
+Unlike forms, they are not constrained to dealing with HTML output, and
+form encoded input.
+
+Serialization in REST framework is a two-phase process:
+
+1. Serializers marshal between complex types like model instances, and
+python primatives.
+2. The process of marshalling between python primatives and request and
+response content is handled by parsers and renderers.
+"""
 from __future__ import unicode_literals
 import copy
 import datetime

rest_framework/throttling.py

@@ -1,3 +1,6 @@
+"""
+Provides various throttling policies.
+"""
 from __future__ import unicode_literals
 from django.core.cache import cache
 from rest_framework import exceptions
@@ -28,9 +31,8 @@ class SimpleRateThrottle(BaseThrottle):
     A simple cache implementation, that only requires `.get_cache_key()`
     to be overridden.
 
-    The rate (requests / seconds) is set by a :attr:`throttle` attribute
+    The rate (requests / seconds) is set by a `throttle` attribute on the View
-    on the :class:`.View` class.  The attribute is a string of the form 'number of
+    class.  The attribute is a string of the form 'number_of_requests/period'.
-    requests/period'.
 
     Period should be one of: ('s', 'sec', 'm', 'min', 'h', 'hour', 'd', 'day')
 

rest_framework/views.py

@@ -1,5 +1,5 @@
 """
-Provides an APIView class that is used as the base of all class-based views.
+Provides an APIView class that is the base of all views in REST framework.
 """
 from __future__ import unicode_literals
 from django.core.exceptions import PermissionDenied

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,19 +79,9 @@ class ViewSetMixin(object):
 
 
 class ViewSet(ViewSetMixin, views.APIView):
-    pass
+    """
-
+    The base ViewSet class does not provide any actions by default.
-
+    """
-# 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,
-                    mixins.DestroyModelMixin,
-                    mixins.ListModelMixin,
-                    ViewSetMixin,
-                    generics.GenericAPIView):
     pass
 
 
@@ -84,4 +89,21 @@ class ReadOnlyModelViewSet(mixins.RetrieveModelMixin,
                            mixins.ListModelMixin,
                            ViewSetMixin,
                            generics.GenericAPIView):
+    """
+    A viewset that provides default `list()` and `retrieve()` actions.
+    """
+    pass
+
+
+class ModelViewSet(mixins.CreateModelMixin,
+                    mixins.RetrieveModelMixin,
+                    mixins.UpdateModelMixin,
+                    mixins.DestroyModelMixin,
+                    mixins.ListModelMixin,
+                    ViewSetMixin,
+                    generics.GenericAPIView):
+    """
+    A viewset that provides default `create()`, `retrieve()`, `update()`,
+    `partial_update()`, `destroy()` and `list()` actions.
+    """
     pass