edits: DOCS-579

Author: Sam Kleinman

source/reference/method/cursor.batchSize.txt

@@ -7,44 +7,42 @@ cursor.batchSize()
 .. method:: cursor.batchSize()
 
    The :method:`batchSize() <cursor.batchSize()>` method specifies the
-   number of documents the cursor returns per batch. Specifying the
-   batchSize is a low-level optimization whose effects are not visible
-   to the user.
+   number of documents the cursor will return in each batch. In most
+   cases, the effect of configuring the batch size will not affect the
+   user or application.
 
    The :method:`batchSize() <cursor.batchSize()>` method takes the
    following parameter:
 
-   :param size: 
-   
-          The number of documents to return per batch. The ``size``
+   :param size:
+
+          The number of documents to return per batch. This value
           also affects whether to close the cursor after the first
           batch. Refer to the specific driver ``batchSize``
           documentation for the cursor behavior as determined by the
           ``size``.
 
-   .. note::
-   
-      The actual number of documents in the batch may be smaller as
-      determined by the limit or the 4 megabyte size limit of the
-      server reply.
-      
-   Consider the following examples of the :method:`batchSize()
+   The :program:`mongo` shell will iterate over 20 documents
+   regardless of the configured batch size, unless you specify a
+   negative batch size.
+
+   Consider the following examples that use the :method:`batchSize()
    <cursor.batchSize()>` method in the :program:`mongo` shell:
-   
+
    - Set the number of documents returned by the :method:`find()
      <db.collection.find()>` method to ``10`` per each batch:
-     
+
      .. code-block:: javascript
 
         var curs = db.animals.find().batchSize(10)
-        
+
      The cursor remains open so that you can iterate through the cursor
      ``curs`` to access all documents in the ``animals`` collection.
 
    - Set the number of documents returned by the :method:`find()
      <db.collection.find()>` method to ``10`` per each batch and close
      after the first batch:
-     
+
      .. code-block:: javascript
 
         var curs = db.animals.find().batchSize(-10)