Fixed #9958: split the `CommentForm` into a set of smaller forms. This for better encapsulation, but also so that it's easier for subclasses to get at the pieces they might need. Thanks to Thejaswi Puthraya.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10110 bcc190cf-cafb-0310-a4f2-bffc1f526a37

3 files changed, 61 insertions, 3 deletions

diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt
index 064bbca6d8..d4b175603b 100644
--- a/docs/ref/contrib/comments/custom.txt
+++ b/docs/ref/contrib/comments/custom.txt
@@ -93,7 +93,12 @@ field::
             data['title'] = self.cleaned_data['title']
             return data
 
-Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to point Django at these classes we've created::
+Django provides a couple of "helper" classes to make writing certain types of
+custom comment forms easier; see :mod:`django.contrib.comments.forms` for
+more.
+
+Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to
+point Django at these classes we've created::
 
     from my_comments_app.models import CommentWithTitle
     from my_comments_app.forms import CommentFormWithTitle
@@ -104,14 +109,18 @@ Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to po
     def get_form():
         return CommentFormWithTitle
 
-The above process should take care of most common situations. For more advanced usage, there are additional methods you can define. Those are explained in the next section.
+The above process should take care of most common situations. For more
+advanced usage, there are additional methods you can define. Those are
+explained in the next section.
 
 .. _custom-comment-app-api:
 
 Custom comment app API
 ======================
 
-The :mod:`django.contrib.comments` app defines the following methods; any custom comment app must define at least one of them. All are optional, however.
+The :mod:`django.contrib.comments` app defines the following methods; any
+custom comment app must define at least one of them. All are optional,
+however.
 
 .. function:: get_model()
 
diff --git a/docs/ref/contrib/comments/forms.txt b/docs/ref/contrib/comments/forms.txt
new file mode 100644
index 0000000000..af0c59a27e
--- /dev/null
+++ b/docs/ref/contrib/comments/forms.txt
@@ -0,0 +1,48 @@
+.. _ref-contrib-comments-forms:
+
+====================
+Comment form classes
+====================
+
+.. module:: django.contrib.comments.forms
+   :synopsis: Forms for dealing with the built-in comment model.
+
+The ``django.contrib.comments.forms`` module contains a handful of forms
+you'll use when writing custom views dealing with comments, or when writing
+:ref:`custom comment apps <ref-contrib-comments-custom>`.
+
+.. class:: CommentForm
+
+   The main comment form representing the standard, built-in way of handling
+   submitted comments. This is the class used by all the views
+   :mod:`django.contrib.comments` to handle submitted comments.
+
+   If you want to build custom views that are similar to Django's built-in
+   comment handling views, you'll probably want to use this form.
+
+Abstract comment forms for custom comment apps
+----------------------------------------------
+
+If you're building a :ref:`custom comment app <ref-contrib-comments-custom>`,
+you might want to replace *some* of the form logic but still rely on parts of
+the existing form.
+
+:class:`CommentForm` is actually composed of a couple of abstract base class
+forms that you can subclass to reuse pieces of the form handling logic:
+
+.. class:: CommentSecurityForm
+
+   Handles the anti-spoofing protection aspects of the comment form handling.
+
+   This class contains the ``content_type`` and ``object_pk`` fields pointing
+   to the object the comment is attached to, along with a ``timestamp`` and a
+   ``security_hash`` of all the form data. Together, the timestamp and the
+   security hash ensure that spammers can't "replay" form submissions and
+   flood you with comments.
+
+.. class:: CommentDetailsForm
+
+   Handles the details of the comment itself.
+
+   This class contains the ``name``, ``email``, ``url``, and the ``comment``
+   field itself, along with the associated valdation logic.
\ No newline at end of file
diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
index b78ac4f36d..f3a59bbbd4 100644
--- a/docs/ref/contrib/comments/index.txt
+++ b/docs/ref/contrib/comments/index.txt
@@ -215,3 +215,4 @@ More information
    signals
    upgrade
    custom
+   forms