Fixed documentation

docs/changelog.rst

@@ -27,7 +27,7 @@ Changes in 0.6.14
 - Added support for add_to_set and each
 
 Changes in 0.6.13
-================
+=================
 - Fixed EmbeddedDocument db_field validation issue
 - Fixed StringField unicode issue
 - Fixes __repr__ modifying the cursor

docs/guide/defining-documents.rst

@@ -259,6 +259,35 @@ as the constructor's argument::
         content = StringField()
 
 
+.. _one-to-many-with-listfields:
+
+One to Many with ListFields
+'''''''''''''''''''''''''''
+
+If you are implementing a one to many relationship via a list of references,
+then the references are stored as DBRefs and to query you need to pass an
+instance of the object to the query::
+
+    class User(Document):
+        name = StringField()
+
+    class Page(Document):
+        content = StringField()
+        authors = ListField(ReferenceField(User))
+
+    bob = User(name="Bob Jones").save()
+    john = User(name="John Smith").save()
+
+    Page(content="Test Page", authors=[bob, john]).save()
+    Page(content="Another Page", authors=[john]).save()
+
+    # Find all pages Bob authored
+    Page.objects(authors__in=[bob])
+
+    # Find all pages that both Bob and John have authored
+    Page.objects(authors__all=[bob, john])
+
+
 Dealing with deletion of referred documents
 '''''''''''''''''''''''''''''''''''''''''''
 By default, MongoDB doesn't check the integrity of your data, so deleting

mongoengine/fields.py

@@ -530,6 +530,8 @@ class ListField(ComplexBaseField):
     """A list field that wraps a standard field, allowing multiple instances
     of the field to be used as a list in the database.
 
+    If using with ReferenceFields see: :ref:`one-to-many-with-listfields`
+
     .. note::
         Required means it cannot be empty - as the default for ListFields is []
     """

mongoengine/queryset.py

@@ -806,9 +806,9 @@ class QuerySet(object):
         keyword argument called :attr:`defaults`.
 
         .. note:: This requires two separate operations and therefore a
-        race condition exists.  Because there are no transactions in mongoDB
-        other approaches should be investigated, to ensure you don't
-        accidently duplicate data when using this method.
+            race condition exists.  Because there are no transactions in mongoDB
+            other approaches should be investigated, to ensure you don't
+            accidently duplicate data when using this method.
 
         :param write_options: optional extra keyword arguments used if we
             have to create a new document.
@@ -816,8 +816,8 @@ class QuerySet(object):
 
         :param auto_save: if the object is to be saved automatically if not found.
 
+        .. versionchanged:: 0.6 - added `auto_save`
         .. versionadded:: 0.3
-        .. versionupdated:: 0.6 - added `auto_save`
         """
         defaults = query.get('defaults', {})
         if 'defaults' in query: