Fixed #18451 -- Vastly improved class based view documentation.

Many thanks to Daniel Greenfeld, James Aylett, Marc Tamlyn, Simon Williams, Danilo Bargen and Luke Plant for their work on this.

5 files changed, 79 insertions, 8 deletions

diff --git a/django/views/generic/base.py b/django/views/generic/base.py
index c45bc32bf5..69751727bb 100644
--- a/django/views/generic/base.py
+++ b/django/views/generic/base.py
@@ -90,6 +90,9 @@ class View(object):
         return http.HttpResponseNotAllowed(self._allowed_methods())
 
     def options(self, request, *args, **kwargs):
+        """
+        Handles responding to requests for the OPTIONS HTTP verb.
+        """
         response = http.HttpResponse()
         response['Allow'] = ', '.join(self._allowed_methods())
         response['Content-Length'] = 0
@@ -108,7 +111,11 @@ class TemplateResponseMixin(object):
 
     def render_to_response(self, context, **response_kwargs):
         """
-        Returns a response with a template rendered with the given context.
+        Returns a response, using the `response_class` for this
+        view, with a template rendered with the given context.
+
+        If any keyword arguments are provided, they will be
+        passed to the constructor of the response class.
         """
         return self.response_class(
             request = self.request,
diff --git a/django/views/generic/dates.py b/django/views/generic/dates.py
index 26b172231c..22a72bc433 100644
--- a/django/views/generic/dates.py
+++ b/django/views/generic/dates.py
@@ -14,6 +14,9 @@ from django.views.generic.detail import BaseDetailView, SingleObjectTemplateResp
 from django.views.generic.list import MultipleObjectMixin, MultipleObjectTemplateResponseMixin
 
 class YearMixin(object):
+    """
+    Mixin for views manipulating year-based data.
+    """
     year_format = '%Y'
     year = None
 
@@ -67,6 +70,9 @@ class YearMixin(object):
 
 
 class MonthMixin(object):
+    """
+    Mixin for views manipulating month-based data.
+    """
     month_format = '%b'
     month = None
 
@@ -123,6 +129,9 @@ class MonthMixin(object):
 
 
 class DayMixin(object):
+    """
+    Mixin for views manipulating day-based data.
+    """
     day_format = '%d'
     day = None
 
@@ -176,6 +185,9 @@ class DayMixin(object):
 
 
 class WeekMixin(object):
+    """
+    Mixin for views manipulating week-based data.
+    """
     week_format = '%U'
     week = None
 
@@ -312,7 +324,7 @@ class DateMixin(object):
 
 class BaseDateListView(MultipleObjectMixin, DateMixin, View):
     """
-    Abstract base class for date-based views display a list of objects.
+    Abstract base class for date-based views displaying a list of objects.
     """
     allow_empty = False
 
diff --git a/django/views/generic/detail.py b/django/views/generic/detail.py
index a5ddb5fe3e..cc0b44512e 100644
--- a/django/views/generic/detail.py
+++ b/django/views/generic/detail.py
@@ -48,6 +48,7 @@ class SingleObjectMixin(ContextMixin):
                                  % self.__class__.__name__)
 
         try:
+            # Get the single item from the filtered queryset
             obj = queryset.get()
         except ObjectDoesNotExist:
             raise Http404(_("No %(verbose_name)s found matching the query") %
@@ -88,6 +89,9 @@ class SingleObjectMixin(ContextMixin):
             return None
 
     def get_context_data(self, **kwargs):
+        """
+        Insert the single object into the context dict.
+        """
         context = {}
         context_object_name = self.get_context_object_name(self.object)
         if context_object_name:
@@ -97,6 +101,9 @@ class SingleObjectMixin(ContextMixin):
 
 
 class BaseDetailView(SingleObjectMixin, View):
+    """
+    A base view for displaying a single object
+    """
     def get(self, request, *args, **kwargs):
         self.object = self.get_object()
         context = self.get_context_data(object=self.object)
@@ -109,8 +116,13 @@ class SingleObjectTemplateResponseMixin(TemplateResponseMixin):
 
     def get_template_names(self):
         """
-        Return a list of template names to be used for the request. Must return
-        a list. May not be called if render_to_response is overridden.
+        Return a list of template names to be used for the request. May not be
+        called if render_to_response is overridden. Returns the following list:
+
+        * the value of ``template_name`` on the view (if provided)
+        * the contents of the ``template_name_field`` field on the
+          object instance that the view is operating upon (if available)
+        * ``<app_label>/<object_name><template_name_suffix>.html``        
         """
         try:
             names = super(SingleObjectTemplateResponseMixin, self).get_template_names()
diff --git a/django/views/generic/edit.py b/django/views/generic/edit.py
index b3ff328344..e51cdf5a3d 100644
--- a/django/views/generic/edit.py
+++ b/django/views/generic/edit.py
@@ -46,6 +46,9 @@ class FormMixin(ContextMixin):
         return kwargs
 
     def get_success_url(self):
+        """
+        Returns the supplied success URL.
+        """
         if self.success_url:
             url = self.success_url
         else:
@@ -54,9 +57,16 @@ class FormMixin(ContextMixin):
         return url
 
     def form_valid(self, form):
+        """
+        If the form is valid, redirect to the supplied URL.
+        """
         return HttpResponseRedirect(self.get_success_url())
 
     def form_invalid(self, form):
+        """
+        If the form is invalid, re-render the context data with the
+        data-filled form and errors.
+        """
         return self.render_to_response(self.get_context_data(form=form))
 
 
@@ -67,7 +77,7 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
 
     def get_form_class(self):
         """
-        Returns the form class to use in this view
+        Returns the form class to use in this view.
         """
         if self.form_class:
             return self.form_class
@@ -94,6 +104,9 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
         return kwargs
 
     def get_success_url(self):
+        """
+        Returns the supplied URL.
+        """
         if self.success_url:
             url = self.success_url % self.object.__dict__
         else:
@@ -106,10 +119,17 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
         return url
 
     def form_valid(self, form):
+        """
+        If the form is valid, save the associated model.
+        """
         self.object = form.save()
         return super(ModelFormMixin, self).form_valid(form)
 
     def get_context_data(self, **kwargs):
+        """
+        If an object has been supplied, inject it into the context with the
+        supplied context_object_name name.
+        """
         context = {}
         if self.object:
             context['object'] = self.object
@@ -122,14 +142,21 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
 
 class ProcessFormView(View):
     """
-    A mixin that processes a form on POST.
+    A mixin that renders a form on GET and processes it on POST.
     """
     def get(self, request, *args, **kwargs):
+        """
+        Handles GET requests and instantiates a blank version of the form.
+        """
         form_class = self.get_form_class()
         form = self.get_form(form_class)
         return self.render_to_response(self.get_context_data(form=form))
 
     def post(self, request, *args, **kwargs):
+        """
+        Handles POST requests, instantiating a form instance with the passed
+        POST variables and then checked for validity.
+        """
         form_class = self.get_form_class()
         form = self.get_form(form_class)
         if form.is_valid():
@@ -172,7 +199,7 @@ class BaseCreateView(ModelFormMixin, ProcessFormView):
 
 class CreateView(SingleObjectTemplateResponseMixin, BaseCreateView):
     """
-    View for creating an new object instance,
+    View for creating a new object instance,
     with a response rendered by template.
     """
     template_name_suffix = '_form'
@@ -196,7 +223,7 @@ class BaseUpdateView(ModelFormMixin, ProcessFormView):
 class UpdateView(SingleObjectTemplateResponseMixin, BaseUpdateView):
     """
     View for updating an object,
-    with a response rendered by template..
+    with a response rendered by template.
     """
     template_name_suffix = '_form'
 
@@ -208,6 +235,10 @@ class DeletionMixin(object):
     success_url = None
 
     def delete(self, request, *args, **kwargs):
+        """
+        Calls the delete() method on the fetched object and then
+        redirects to the success URL.
+        """
         self.object = self.get_object()
         self.object.delete()
         return HttpResponseRedirect(self.get_success_url())
diff --git a/django/views/generic/list.py b/django/views/generic/list.py
index 2e852699d5..ec30c58f29 100644
--- a/django/views/generic/list.py
+++ b/django/views/generic/list.py
@@ -8,6 +8,9 @@ from django.views.generic.base import TemplateResponseMixin, ContextMixin, View
 
 
 class MultipleObjectMixin(ContextMixin):
+    """
+    A mixin for views manipulating multiple objects.
+    """
     allow_empty = True
     queryset = None
     model = None
@@ -111,6 +114,9 @@ class MultipleObjectMixin(ContextMixin):
 
 
 class BaseListView(MultipleObjectMixin, View):
+    """
+    A base view for displaying a list of objects.
+    """
     def get(self, request, *args, **kwargs):
         self.object_list = self.get_queryset()
         allow_empty = self.get_allow_empty()
@@ -132,6 +138,9 @@ class BaseListView(MultipleObjectMixin, View):
 
 
 class MultipleObjectTemplateResponseMixin(TemplateResponseMixin):
+    """
+    Mixin for responding with a template and list of objects.
+    """
     template_name_suffix = '_list'
 
     def get_template_names(self):