From 008a62e4e93503b755a526b52267c1c6035bbdea Mon Sep 17 00:00:00 2001
From: blackbrrr <mattdennewitz@gmail.com>
Date: Fri, 12 Feb 2010 16:07:44 -0600
Subject: [PATCH] updated map/reduce documentation

---
 mongoengine/queryset.py | 21 +++++++--------------
 tests/queryset.py       |  3 +++
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/mongoengine/queryset.py b/mongoengine/queryset.py
index 32840471..9c706f0d 100644
--- a/mongoengine/queryset.py
+++ b/mongoengine/queryset.py
@@ -387,36 +387,29 @@ class QuerySet(object):
         and ordering. While ``map_reduce`` respects ``QuerySet`` chaining, 
         it must be the last call made, as it does not return a maleable 
         ``QuerySet``. 
-        
-        Example: map/reduce operation is given a ``QuerySet`` 
-        of all posts by "mattdennewitz", ordered by most recent "pub_date". ::
-        
-            map_f = function() { ... }
-            reduce_f = function(key, values) { ... }
-        
-            posts = BlogPost(author="mattdennewitz").order_by("-pub_date")
-            tag_counts = posts.map_reduce(map_f, reduce_f)
             
-        See the :meth:`~mongoengine.tests.QuerySetTest.test_map_reduce_simple` 
-        unit test for more usage examples.
+        See the :meth:`~mongoengine.tests.QuerySetTest.test_map_reduce` 
+        and :meth:`~mongoengine.tests.QuerySetTest.test_map_advanced`
+        tests in ``tests.queryset.QuerySetTest`` for usage examples.
     
         :param map_f: map function, as :class:`~pymongo.code.Code` or string
         :param reduce_f: reduce function, as 
                          :class:`~pymongo.code.Code` or string
+        :param finalize_f: finalize function, an optional function that
+                           performs any post-reduction processing.
         :param scope: values to insert into map/reduce global scope. Optional.
         :param limit: number of objects from current query to provide
                       to map/reduce method
         :param keep_temp: keep temporary table (boolean, default ``True``)
         
-        Returns a list of :class:`~mongoengine.document.MapReduceDocument`.
+        Returns an iterator yielding 
+        :class:`~mongoengine.document.MapReduceDocument`.
         
         .. note:: Map/Reduce requires server version **>= 1.1.1**. The PyMongo
            :meth:`~pymongo.collection.Collection.map_reduce` helper requires
            PyMongo version **>= 1.2**.
            
         .. versionadded:: 0.2.2
-        
-        .. todo:: Implement limits
 
         """
         from document import MapReduceDocument
diff --git a/tests/queryset.py b/tests/queryset.py
index 777231e9..809f9f8e 100644
--- a/tests/queryset.py
+++ b/tests/queryset.py
@@ -601,7 +601,10 @@ class QuerySetTest(unittest.TestCase):
         results = results.map_reduce(map_f, reduce_f, finalize_f=finalize_f)
         results = list(results)
         
+        # assert troublesome Buzz article is ranked 1st
         self.assertTrue(results[0].object.title.startswith("Google Buzz"))
+        
+        # assert laser vision is ranked last
         self.assertTrue(results[-1].object.title.startswith("How to see"))
 
         Link.drop_collection()