Added some explanatory docstrings and comments.

mock_django/managers.py

@@ -24,6 +24,8 @@ def ManagerMock(manager, *return_value):
     Force an exception:
 
     >>> objects = ManagerMock(Post.objects, Exception())
+
+    See QuerySetMock for more about how this works.
     """
 
     def make_get_query_set(self, model):

mock_django/query.py

@@ -22,6 +22,13 @@ def QuerySetMock(model, *return_value):
     Force an exception:
 
     >>> objects = QuerySetMock(Post, Exception())
+
+    Note that only methods returning querysets are currently
+    explicitly supported; since we use SharedMock, others all behave
+    as if they did, so use with caution:
+
+    >>> objects.count() == objects.all()
+    True
     """
 
     def make_get(self, model):
@@ -69,5 +76,9 @@ def _iterator(*a, **k):
     m.__getitem__.side_effect = make_getitem(m)
     m.model = model
     m.get = make_get(m, actual_model)
+
+    # Note since this is a SharedMock, *all* auto-generated child
+    # attributes will have the same side_effect ... might not make
+    # sense for some like count().
     m.iterator.side_effect = make_iterator(m)
     return m

mock_django/shared.py

@@ -2,6 +2,28 @@
 
 
 class SharedMock(mock.MagicMock):
+
+    """
+    A MagicMock whose children are all itself.
+
+    >>> m = SharedMock()
+    >>> m is m.foo is m.bar is m.foo.bar.baz.qux
+    True
+    >>> m.foo.side_effect = ['hello from foo']
+    >>> m.bar()
+    'hello from foo'
+
+    'Magic' methods are not shared.
+    >>> m.__getitem__ is m.__len__
+    False
+
+    Neither are attributes you assign.
+    >>> m.explicitly_assigned_attribute = 1
+    >>> m.explicitly_assigned_attribute is m.foo
+    False
+
+    """
+
     def __init__(self, *args, **kwargs):
         super(SharedMock, self).__init__(*args, **kwargs)
         parent = mock.MagicMock()
@@ -23,11 +45,16 @@ def __getattr__(self, name):
     def assert_chain_calls(self, *calls):
         """
         Asserts that a chained method was called (parents in the chain do not
-        matter, nor are they tracked).
+        matter, nor are they tracked).  Use with `mock.call`.
+
+        >>> obj.filter(foo='bar').select_related('baz')
+        >>> obj.assert_chain_calls(mock.call.filter(foo='bar'))
+        >>> obj.assert_chain_calls(mock.call.select_related('baz'))
+        >>> obj.assert_chain_calls(mock.call.reverse())
+        *** AssertionError: [call.reverse()] not all found in call list, ...
 
-        >>> obj.assert_chain_calls(call.filter(foo='bar'))
-        >>> obj.assert_chain_calls(call.select_related('baz'))
         """
+
         all_calls = self.__parent.mock_calls[:]
 
         not_found = []

tests/mock_django/managers/tests.py

@@ -38,7 +38,6 @@ def test_getitem(self):
     def test_returns_self(self):
         manager = make_manager()
         inst = ManagerMock(manager, 'foo')
-
         self.assertEquals(inst.all(), inst)
 
     def test_get_on_singular_list(self):