Updated docs regarding ReferenceFields

Closes #149

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

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 '