Fixed #8326: added signals documentation.

Thanks to MercuryTide's signal whitepaper from 2006 (http://www.mercurytide.co.uk/whitepapers/django-signals/) for inspiration and ideas for organization, and to the folks who got the Signals wiki page together for some of the content.


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

2 files changed, 89 insertions, 0 deletions

diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
index 1e9418b55a..443c89d3c1 100644
--- a/docs/ref/contrib/comments/index.txt
+++ b/docs/ref/contrib/comments/index.txt
@@ -208,5 +208,6 @@ More information
    :maxdepth: 1
 
    settings
+   signals
    upgrade
 
diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt
new file mode 100644
index 0000000000..d3fd85cad5
--- /dev/null
+++ b/docs/ref/contrib/comments/signals.txt
@@ -0,0 +1,88 @@
+.. _ref-contrib-comments-signals:
+
+================================
+Signals sent by the comments app
+================================
+
+.. module:: django.contrib.comments.signals
+   :synopsis: Signals sent by the comment module.
+
+The comment app sends a series of :ref:`signals <topics-signals>` to allow for
+comment moderation and similar activities. See :ref:`the introduction to signals
+<topics-signals>` for information about how to register for and receive these
+signals.
+
+comment_will_be_posted
+======================
+
+.. data:: django.contrib.comments.signals.comment_will_be_posted
+
+Sent just before a comment will be saved, after it's been sanity checked and
+submitted. This can be used to modify the comment (in place) with posting
+details or other such actions.
+
+If any receiver returns ``False`` the comment will be discarded and a 403 (not
+allowed) response will be returned.
+
+This signal is sent at more or less the same time (just before, actually) as the
+``Comment`` object's :data:`~django.db.models.signals.pre_save` signal.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance about to be posted. Note that it won't have been
+        saved into the database yet, so it won't have a primary key, and any
+        relations might not work correctly yet.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
+        
+comment_was_posted
+==================
+
+.. data:: django.contrib.comments.signals.comment_was_posted
+
+Sent just after the comment is saved.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance that was posted. Note that it will have already
+        been saved, so if you modify it you'll need to call
+        :meth:`~django.db.models.Model.save` again.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
+
+comment_was_flagged
+===================
+
+Sent after a comment was "flagged" in some way. Check the flag to see if this
+was a user requesting removal of a comment, a moderator approving/removing a
+comment, or some other custom user flag.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance that was posted. Note that it will have already
+        been saved, so if you modify it you'll need to call
+        :meth:`~django.db.models.Model.save` again.
+        
+    ``flag``
+        The :class:`~django.contrib.comments.models.CommentFlag` that's been
+        attached to the comment.
+        
+    ``created``
+        ``True`` if this is a new flag; ``False`` if it's a duplicate flag.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.