From b1cdd1eb268680aa0425aead0f1080560f080e5c Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Wed, 25 May 2011 12:01:41 +0100
Subject: [PATCH] Updated docs regarding ReferenceFields

Closes #149
---
 docs/tutorial.rst     | 15 +++++++++++++++
 mongoengine/fields.py | 15 +++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index 5db2c4df..63f8fe9b 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -152,6 +152,21 @@ We can then store a list of comment documents in our post document::
         tags = ListField(StringField(max_length=30))
         comments = ListField(EmbeddedDocumentField(Comment))
 
+Handling deletions of references
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :class:`~mongoengine.ReferenceField` object takes a keyword
+`reverse_delete_rule` for handling deletion rules if the reference is deleted.
+To delete all the posts if a user is deleted set the rule::
+
+    class Post(Document):
+        title = StringField(max_length=120, required=True)
+        author = ReferenceField(User, reverse_delete_rule=CASCADE)
+        tags = ListField(StringField(max_length=30))
+        comments = ListField(EmbeddedDocumentField(Comment))
+
+See :class:`~mongoengine.ReferenceField` for more information.
+
 Adding data to our Tumblelog
 ============================
 Now that we've defined how our documents will be structured, let's start adding
diff --git a/mongoengine/fields.py b/mongoengine/fields.py
index 11366dd0..b12c507f 100644
--- a/mongoengine/fields.py
+++ b/mongoengine/fields.py
@@ -555,9 +555,24 @@ class MapField(BaseField):
 class ReferenceField(BaseField):
     """A reference to a document that will be automatically dereferenced on
     access (lazily).
+
+    Use the `reverse_delete_rule` to handle what should happen if the document
+    the field is referencing is deleted.
+
+    The options are:
+
+      * DO_NOTHING  - don't do anything (default).
+      * NULLIFY     - Updates the reference to null.
+      * CASCADE     - Deletes the documents associated with the reference.
+      * DENY        - Prevent the deletion of the reference object.
     """
 
     def __init__(self, document_type, reverse_delete_rule=DO_NOTHING, **kwargs):
+        """Initialises the Reference Field.
+
+        :param reverse_delete_rule: Determines what to do when the referring
+          object is deleted
+        """
         if not isinstance(document_type, basestring):
             if not issubclass(document_type, (Document, basestring)):
                 raise ValidationError('Argument to ReferenceField constructor '